gpt-engineer User Guide

gpt-engineer is a command-line tool that turns a plain-English description into a working codebase. You write what you want in a single text file, run one command, and an AI model writes the source files, proposes a script to run them, and — with your permission — executes that script. You can also point it at an existing project and ask it to make changes.

This guide covers everything you need to install gpt-engineer, configure an AI model, generate and improve projects, and work with its specialized modes. It is written against gpt-engineer 0.3.1.

Note

gpt-engineer generates and can execute code written by a language model. Treat every generated project the way you would treat code from an untrusted source: read it before you run it, and prefer to run it in a throwaway folder or container. See Generated code and safety.

1. Quick Start

This is the shortest path from nothing to a generated project.

Stable (PyPI)

python -m pip install gpt-engineer
export OPENAI_API_KEY="sk-your-key-here"

mkdir my-project
echo "a simple command-line snake game in Python" > my-project/prompt

gpte my-project

From source (Poetry)

git clone https://github.com/gpt-engineer-org/gpt-engineer.git
cd gpt-engineer
poetry install
poetry shell

export OPENAI_API_KEY="sk-your-key-here"
mkdir -p projects/my-project
echo "a simple command-line snake game in Python" > projects/my-project/prompt

gpte projects/my-project

What happens when you run gpte my-project:

1. gpt-engineer reads the prompt file in the folder you named.
2. The AI writes the code and prints each file as it goes.
3. The AI writes a run.sh script that installs dependencies and runs the code.
4. You are asked Do you want to execute this code? (Y/n) — press Enter to run it, or type n to skip.
5. Generated files are saved inside your project folder.

Running gpt-engineer in /home/you/my-project

... (the AI streams the generated files here) ...

Do you want to execute this code? (Y/n)

Tip

The command is available under three identical names: gpte, ge, and gpt-engineer. They are aliases for the same program. This guide uses gpte.

2. Installation

2.1 Requirements

Note

The last release to support Python 3.8–3.9 was 0.2.6. On current releases you need Python 3.10 or newer.

2.2 Install the stable release

python -m pip install gpt-engineer

Successfully installed gpt-engineer-0.3.1 ...

This installs the gpte, ge, gpt-engineer, and bench commands onto your PATH.

2.3 Install from source (for development or the latest code)

Source installs use Poetry:

git clone https://github.com/gpt-engineer-org/gpt-engineer.git
cd gpt-engineer
poetry install
poetry shell

poetry shell activates the virtual environment so the gpte command is on your PATH. If you prefer the bundled Makefile:

make install        # runs `poetry install` plus installs pre-commit hooks

2.4 Verify the install

gpte --help

Usage: gpte [OPTIONS] [PROJECT_PATH]

  GPT-engineer lets you:

  - Specify a software in natural language
  - Sit back and watch as an AI writes and executes the code
  - Ask the AI to implement improvements
...

If you see the usage text, gpt-engineer is installed correctly. If the command is not found, see Troubleshooting.

3. Set Up an AI Model

gpt-engineer talks to a language model through a provider API. You must supply at least one key. The default model is gpt-4o (OpenAI).

3.1 Provide a key

Choose one of these methods.

Environment variable (Linux/macOS)

export OPENAI_API_KEY="sk-your-key-here"

Add the line to ~/.bashrc (or ~/.zshrc) so you don't have to set it every session.

Environment variable (Windows)

set OPENAI_API_KEY=sk-your-key-here          (cmd)
$env:OPENAI_API_KEY="sk-your-key-here"       (PowerShell)

.env file

Create a file named .env in the directory you run gpt-engineer from. Start from the bundled template .env.template:

OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here

Important

If OPENAI_API_KEY is not already set in your environment, gpt-engineer automatically loads a .env file from your current working directory at startup. The same applies to ANTHROPIC_API_KEY.

3.2 Choose a provider and model

The provider is selected automatically from the model name you pass with --model/-m.

Examples:

gpte my-project --model gpt-4o
gpte my-project --model claude-3-5-sonnet-20240620
gpte my-project --model gpt-4-vision-preview        # vision-capable

Tip

You can set a default model without typing --model every time by exporting the MODEL_NAME environment variable:

export MODEL_NAME="claude-3-5-sonnet-20240620"

3.3 Azure OpenAI

For Azure, the value you pass to --model is the deployment name you chose in Azure AI Studio, and you must supply the service endpoint:

gpte my-project --model my-deployment-name \
  --azure "https://your-resource.openai.azure.com"

The Azure API version defaults to 2024-05-01-preview. Override it with the OPENAI_API_VERSION environment variable if your resource requires a different version.

3.4 Local and alternative models

gpt-engineer can drive open-source models (for example, CodeLlama served locally) as long as they are exposed through an OpenAI-compatible API. This requires extra setup — running a local inference server such as llama-cpp-python and pointing the OpenAI client at it. The full procedure lives in the project's open models documentation; model configuration internals are covered in the Admin Guide.

Note

When you run against a local model, set the LOCAL_MODEL environment variable so gpt-engineer prints Total api cost: $ 0.0 instead of trying to compute a dollar cost.

4. Generate a New Project

This is the default mode — no flags required.

4.1 The prompt file

Every project lives in its own folder. Inside that folder you create a file named prompt (no file extension) containing your instructions in plain language.

mkdir todo-api
cat > todo-api/prompt <<'EOF'
A REST API for a todo list, written in Python with FastAPI.
It should support creating, listing, completing, and deleting todos.
Store todos in an in-memory list. Include a requirements.txt.
EOF

Tip

Be specific about language, framework, and how the program should be run. The more concrete your prompt, the closer the result. gpt-engineer's built-in guidance already nudges the AI toward idiomatic structure (one class per file, a requirements.txt for Python, a package.json for Node, etc.).

4.2 Run it

gpte todo-api

Running gpt-engineer in /home/you/todo-api

main.py
```python
from fastapi import FastAPI
...

requirements.txt

fastapi
uvicorn

Do you want to execute this code? (Y/n)

Press Enter (or `y`) to let gpt-engineer run the generated `run.sh`; type `n` to keep the files without running them.

### 4.3 Where the output goes

Generated files are written **into your project folder**. gpt-engineer also creates a hidden `.gpteng/` directory there for its own bookkeeping (logs and metadata) — you can ignore it day to day.

| Path | What it is |
|---|---|
| `<project>/` | The generated source files |
| `<project>/run.sh` | The install-and-run script the AI produced |
| `<project>/.gpteng/memory/logs/` | Full transcripts of each step (useful for debugging) |

> [!NOTE]
> If a `git` repository is present (or gpt-engineer initializes one for you), your existing files are staged before new content overwrites them, so you can always diff or revert. See [Section 8](#8-your-files-are-protected-by-git).

---

## 5. Improve an Existing Project

Improve mode (`--improve` / `-i`) points gpt-engineer at code that already exists and applies targeted edits as diffs.

### 5.1 Run improve mode

Put a `prompt` file describing the change into the project folder, then:

```bash
gpte my-existing-project -i

The flow is:

1. File selection. gpt-engineer opens an editor with a list of every file in the project. You uncomment the files you want the AI to see and edit, save, and close.
2. Linting. Selected Python files are formatted with black before being sent (improves the quality of the AI's edits). You can turn this off — see below.
3. Editing. The AI returns its changes as a unified git diff, which gpt-engineer validates and applies.
4. Review. You see a colorized diff of exactly what will change and are asked Do you want to apply these changes?

5.2 The file-selection editor

When file selection opens, you see a TOML list. Lines beginning with # are deselected; remove the # to include a file:

# Remove '#' to select a file or turn off linting.
[files]
# "src/app.py" = "selected"
"src/models.py" = "selected"
# "tests/test_app.py" = "selected"

Save and close the editor to continue. gpt-engineer picks the editor from your EDITOR environment variable; if that is unset it tries gedit, notepad, nvim, write, nano, vim, and emacs in turn.

Tip

Only select the files that are actually relevant to the change. Including unnecessary files costs tokens, can hit the model's context limit, and tends to lower the quality of the result.

To skip the interactive editor and reuse a previously saved selection, add --skip-file-selection (-s):

gpte my-existing-project -i -s

To disable black linting, uncomment the linting line in the selection file:

[linting]
"linting" = "off"

5.3 If no changes are applied

If the AI returns nothing usable, you'll see:

No changes applied. Could you please upload the debug_log_file.txt in
<project>/.gpteng/memory/logs folder in a github issue?

This usually means the prompt was too vague or the wrong files were selected. Re-run, refine the prompt, and reselect files. If diffs are timing out, raise --diff_timeout (see Section 7).

6. Generation Modes

Beyond the default generate and improve flows, gpt-engineer offers modes that change how the AI works. Combine them with a project path like any other flag.

6.1 Clarify mode (--clarify / -c)

The AI reads your prompt and asks clarifying questions before writing any code. Answer in plain text, or type c to let it proceed on its own assumptions.

gpte my-project -c

(answer in text, or "c" to move on)
Should the todo list persist between runs, or is in-memory storage fine?
> in-memory is fine

Use clarify mode when your requirements are loose and you want the AI to pin down the details with you first.

6.2 Lite mode (--lite / -l)

A fast, single-pass generation that uses only your main prompt with minimal scaffolding. No clarifying questions, no separate reasoning step.

gpte my-project -l

Use lite mode for small, well-specified tasks where you want speed and lower token usage.

6.3 Self-heal mode (--self-heal / -sh)

After generating the code, gpt-engineer runs it, and if it fails, feeds the error output back to the AI to fix automatically — repeating up to 10 times.

gpte my-project -sh

Use self-heal when you want a best-effort runnable result without babysitting each failure. Because it executes the generated code on each attempt, only use it in an environment you're comfortable running untrusted code in.

6.4 Vision mode (images as input)

Vision-capable models can read images alongside your text prompt — handy for handing the AI a UI mockup or architecture diagram. Point --image_directory at a folder of images and use a vision model:

gpte projects/example-vision gpt-4-vision-preview \
  --prompt_file prompt/text \
  --image_directory prompt/images \
  -i

Note

Vision is detected from the model name. Models with vision-preview, non-preview gpt-4-turbo, or claude in the name are treated as vision-capable. If you supply images but use a non-vision model, the images are ignored.

6.5 Clipboard mode (--llm-via-clipboard)

For situations where you can't (or don't want to) call an API directly, clipboard mode copies the full prompt to your clipboard (and writes it to clipboard.txt). You paste it into a chat UI yourself, then paste the model's reply back into the terminal.

gpte my-project --llm-via-clipboard

Enter/Paste your content. Ctrl-D or Ctrl-Z ( windows ) to save it.

6.6 Mode compatibility

Warning

Improve mode cannot be combined with clarify or lite mode. Running gpte -i -c or gpte -i -l exits with:

Error: Clarify and lite mode are not compatible with improve mode.

7. Command-Line Reference

Full option list for gpte / ge / gpt-engineer. The single positional argument is the project path.

7.1 Useful combinations

# Generate, asking questions first, with a specific model
gpte my-project -c -m gpt-4o

# Improve, reusing a saved file selection, with a longer diff timeout
gpte my-project -i -s --diff_timeout 10

# Cheap, repeatable runs while iterating on a prompt
gpte my-project --use_cache

# Collect environment details to paste into a bug report
gpte --sysinfo

Tip

--use_cache stores responses keyed on the request, so running the same prompt again returns the cached answer instantly and for free. Delete .langchain.db to clear it.

8. Your Files Are Protected by Git

When gpt-engineer is about to overwrite files in a project that is a git repository, it first stages your uncommitted changes, so nothing is silently lost:

Staging the following uncommitted files before overwriting:  src/app.py, README.md

In default (generate) mode, if the target folder is not yet a git repo, gpt-engineer initializes an empty one for you:

Initializing an empty git repository

Tip

After a run, use git diff (or git stash list) to see exactly what the AI changed, and git checkout -- <file> to revert anything you don't want.

9. Generated Code and Safety

gpt-engineer writes a run.sh script and offers to execute it. This runs AI-generated commands on your machine.

• You are always prompted before execution (Do you want to execute this code? (Y/n)). Type n to inspect first.
• Read run.sh and the generated files before running them, especially anything that installs packages or touches files outside the project.
• Prefer to generate into a fresh, empty folder — or run inside Docker (see the Admin Guide) — so a mistake can't damage unrelated work.
• During execution you can press Ctrl+C once to stop.

Caution

Self-heal mode (-sh) executes the generated code repeatedly without pausing for each attempt. Only use it where running untrusted code is acceptable.

gpt-engineer can also send anonymized prompt data to its maintainers to improve the tool, but only if you opt in. The first time it would collect feedback it asks:

Is it ok if we store your prompts to help improve GPT Engineer? (y/n)

Answering n disables collection. If you previously consented and change your mind, delete the .gpte_consent file in your working directory.

10. Troubleshooting

Each entry shows the exact message, its cause, and how to fix it.

Error: No files were selected. Please select at least one file to proceed.

Cause: In improve mode, you saved the file-selection list without un-commenting any files. Solution: Re-run gpte <project> -i. In the editor, remove the leading # from at least one file line, then save and close. Prevention: Select only the relevant files, but make sure at least one is active.

Error: The path to the prompt, <path>, already exists as a directory.

Cause: The value passed to --prompt_file points at a directory, not a text file. Solution: Point --prompt_file at an actual file (the default is a file named prompt).

Error: The provided file at --entrypoint-prompt does not exist

Cause: The --entrypoint_prompt path doesn't resolve to a file inside the project. Solution: Use a path relative to the project folder that points to an existing file.

Error: The provided --image_directory is not a directory. / ... is empty.

Cause: --image_directory points at something that isn't a folder, or at an empty folder. Solution: Pass a folder that exists and contains at least one image, and use a vision-capable model.

Error: The required entrypoint run.sh does not exist in the code.

Cause: Execution or self-heal was requested but the AI did not produce a run.sh. Solution: Re-run; if it recurs, make the prompt clearer about how the program should run, or provide --entrypoint_prompt.

Error: Clarify and lite mode are not compatible with improve mode.

Cause: You combined -i with -c or -l. Solution: Use improve mode on its own: gpte <project> -i.

Message: gpt-engineer timed out while parsing git diff

Cause: In improve mode, the regex that parses the AI's diff exceeded the default 3-second budget on a large or complex diff. Solution: Increase the budget, e.g. --diff_timeout 10 (or higher).

Message: GPT did not provide any proposed changes.

Cause: The model's reply contained no valid diff blocks. Solution: Reselect the files for upload and refine the prompt to be more specific about the change you want.

Issue: gpte: command not found

Cause: The console scripts aren't on your PATH. Solution: If you installed from source, activate the environment with poetry shell. For a pip install, ensure your Python scripts directory is on PATH.

Windows: Could not locate file 'C:\Python311\Scripts\tqdm.exe'

Cause: A known Windows packaging hiccup with a transitive dependency (community issue #874). Solution: Reinstall the offending dependency, or run gpt-engineer inside Docker / WSL where the environment is clean.

Error: ValueError: too many values to unpack / issubclass() arg 1 must be a class

Cause: Community-reported errors (issues #133, #1260) that have surfaced with certain model or dependency combinations. Solution: Make sure you're on a supported Python (3.10–3.12) and the latest gpt-engineer; capture details with gpte --sysinfo when reporting.

Tip

For any crash, run gpte --sysinfo and attach its output, plus .gpteng/memory/logs/debug_log_file.txt from your project, when filing an issue.

11. Frequently Asked Questions

Q: What's the difference between gpte, ge, and gpt-engineer? Nothing — they are three names for the same command. Use whichever you prefer.

Q: Do I need an OpenAI key, or can I use Claude / a local model? Any one provider is enough. Set OPENAI_API_KEY for OpenAI/Azure, ANTHROPIC_API_KEY for Claude, and choose the model with --model. Local models work with extra setup.

Q: Where does the generated code end up? Directly in your project folder. gpt-engineer also writes a hidden .gpteng/ folder there for logs and metadata.

Q: How do I stop it from running the generated code automatically? Answer n at the Do you want to execute this code? (Y/n) prompt. Avoid --self-heal, which executes without pausing each time.

Q: Can I see what the AI did, step by step? Yes. Look in <project>/.gpteng/memory/logs/ — all_output.txt, improve.txt, diff_errors.txt, and debug_log_file.txt hold the full transcripts.

Q: How do I keep costs down while iterating? Use --use_cache so repeated runs of the same prompt are free, prefer --lite for small tasks, and select only the files you need in improve mode.

Q: Can I change the AI's "personality" or coding conventions? Yes. Pass --use-custom-preprompts to copy the prompt templates into your project, then edit them. This is how you make the agent remember conventions across projects. The templates are described in the Admin Guide.

Q: It asked to store my prompts. Is that required? No. Data collection is opt-in. Answer n, or delete .gpte_consent to revoke a prior yes.

Q: My diffs keep timing out in improve mode. What do I do? Raise --diff_timeout (e.g. --diff_timeout 10). The default is 3 seconds.

Q: How do I run a benchmark against my own agent? gpt-engineer installs a separate bench command for evaluating agents against datasets like APPS and MBPP. That's an advanced/developer workflow — see the Admin Guide.

Q: Is there a Docker option? Yes. The project ships a Dockerfile and docker-compose.yml. Setup and operational details are in the Admin Guide.

Q: Which Python versions are supported? 3.10, 3.11, and 3.12. For 3.8–3.9, use the older 0.2.6 release.