Skip to content
Get packs

Guide · Open source

How to use screenshot-to-code: install, run and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

Screenshot to Code is an open-source tool (MIT licence, written in Python) that takes a screenshot, mockup, Figma design or screen recording and uses AI models to write front-end code that tries to match the original. This guide is for developers and designers who want a working first draft of a page. By the end you will know what you need before starting, how to run it locally or with Docker, and how to pick a stack.

Screenshot to Codeabi/screenshot-to-code · ★ 81k · MIT

Quick start

  1. 1Check prerequisites. Install Python, Poetry, pnpm and, optionally, Docker. Get at least one API key from OpenAI, Anthropic or Gemini.
  2. 2Clone the repository. Run git clone https://github.com/abi/screenshot-to-code to download the project.
  3. 3Add your API keys. Create backend/.env with your keys, or enter OpenAI, Anthropic and Gemini keys in the frontend settings dialog.
  4. 4Install backend dependencies. Run poetry install in the backend folder, then poetry run playwright install chromium for the screenshot preview.
  5. 5Start the backend. Run poetry run uvicorn main:app --reload --port 7001 from the backend folder.
  6. 6Start the frontend. In the frontend folder run pnpm install and pnpm dev, then open http://localhost:5173.
  7. 7Convert a screenshot. Choose a stack, upload a screenshot, mockup, Figma design or screen recording, and review the generated code.

What you need before you start

Running the project locally requires at least one model provider API key. The README says you need one of OpenAI, Anthropic or Gemini. Gemini and Replicate are strongly recommended for the best quality, because Gemini extracts real assets from the screenshot and Replicate powers image editing, background removal and image generation.

  • Python
  • Poetry (install with pip install --upgrade poetry if you don't have it)
  • pnpm
  • Chromium, installed through Playwright, optional for the screenshot preview tool
  • Docker, optional, for the Docker setup

Get your API keys

Add keys to backend/.env. The README lists OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY and REPLICATE_API_KEY. Each key unlocks a set of models. With more keys, the app picks a stronger mix of models for each variant; with one key it uses only that provider's models.

You can also enter OpenAI, Anthropic and Gemini keys in the settings dialog in the frontend (the gear icon). Replicate must be set in backend/.env.

  • OPENAI_API_KEY: GPT code-gen variants
  • ANTHROPIC_API_KEY: Claude code-gen variants
  • GEMINI_API_KEY: Gemini code-gen variants, asset extraction, and required for video mode
  • REPLICATE_API_KEY: image editing and background removal
echo "OPENAI_API_KEY=sk-your-key" > .env

Install and run it locally

Clone the repository, install the backend dependencies, then install the Chromium browser used by the screenshot preview. Start the backend with uvicorn on port 7001.

In a second terminal, install the frontend dependencies and start the dev server. Open http://localhost:5173 in your browser to use the app.

If you run the backend on a different port, update VITE_WS_BACKEND_URL in frontend/.env.local.

git clone https://github.com/abi/screenshot-to-code cd backend && poetry install poetry run playwright install chromium poetry run uvicorn main:app --reload --port 7001 cd frontend && pnpm install pnpm dev

Run it with Docker instead

If you have Docker installed, you can skip the manual setup. Run the commands from the root directory of the project. The app will be available at http://localhost:5173.

Docker is a run-only setup: the README notes that you can't develop the application this way because file changes won't trigger a rebuild. Use the local setup if you plan to customize the code.

echo "OPENAI_API_KEY=sk-your-key" > .env docker-compose up -d --build

Choose a stack and turn a screenshot into code

Pick the output stack that fits your project. The supported options are HTML with Tailwind, HTML with CSS, React with Tailwind, Vue with Tailwind, Bootstrap, and Ionic with Tailwind. Then drop in a screenshot, mockup, Figma design or screen recording.

The README presents the output as a starting point. Expect to review and adjust the generated code rather than ship it as is.

  • Use a clean, high-resolution screenshot of a single screen.
  • Start with HTML + Tailwind if you want the simplest output to read.
  • Use screen recordings to prototype a website in action.

Troubleshoot common setup problems

Most setup issues are covered in the README FAQ. If a backend setup error persists, the README links to a fix thread and asks you to open an issue. If you can't reach the OpenAI API directly, you can set OPENAI_BASE_URL in backend/.env or in the settings dialog. The URL must include v1 in the path.

  • On Windows, if you see UTF-8 errors, open .env in Notepad++, go to Encoding and select UTF-8.
  • If the screenshot preview is unavailable, install Chromium; the Settings dialog shows whether it is available.
  • To point the frontend at another backend host, set VITE_HTTP_BACKEND_URL and VITE_WS_BACKEND_URL in frontend/.env.local.

What people use it for

  • Getting a first-draft HTML and Tailwind page from a design image.
  • Showing a client a rough coded version of a mockup.
  • Prototyping a website from a screen recording of it in action.
  • Self-hosting the tool and customizing the generated code for your own stack.

Frequently asked questions

Is screenshot-to-code free?

The project is released under the MIT licence and the source is on GitHub. Running it locally still requires at least one API key from a model provider such as OpenAI, Anthropic or Gemini, so you pay those providers for model use. The README does not list prices.

What do I need to run screenshot-to-code?

You need Python, Poetry and pnpm for the local setup, plus at least one API key from OpenAI, Anthropic or Gemini. Chromium is optional and enables the screenshot preview, and Docker is optional for the containerised setup.

Can I run screenshot-to-code offline or with Ollama?

The README says you can run the app with Ollama open-source models, but it is not recommended due to poor-quality results, and it links to a separate comment with instructions. Because the project needs at least one model provider key, it is not designed for fully offline use.

Why is my backend setup failing?

The README FAQ links to a community fix for common backend setup errors. If that doesn't help, open an issue on the project's GitHub repository. On Windows, UTF-8 errors can often be fixed by saving the .env file as UTF-8 in Notepad++.

Can I use it if I can't reach the OpenAI API directly?

Yes, according to the README. You can try a VPN or set OPENAI_BASE_URL in backend/.env or in the settings dialog to use a proxy. Make sure the URL includes v1 in the path.

Is the generated code production-ready?

No guarantee is made. The README presents results as a starting point, so review the code, check layout and responsiveness, and test it before using it in production.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Screenshot to Code suits developers and designers who want a fast first draft of a page from an image, and who are happy to self-host and edit the output. It is a poor fit if you need pixel-perfect or production-ready code without review, have no budget for paid model APIs, or need fully offline operation.

Install options & downloads