In FastAPI, how do the `fastapi dev` and `fastapi run` commands differ, and which one belongs in production?
answer
- two sets of defaults, one server
- reload on or off
- loopback versus every interface
- only one takes --workers
basics
~10 sBoth start Uvicorn with your app. fastapi dev binds 127.0.0.1 with auto-reload for local work; fastapi run binds 0.0.0.0 without reload and accepts --workers, so fastapi run is the production and container command.
solid answer
~40 sBoth commands come from fastapi-cli, which `fastapi[standard]` installs, and both call `uvicorn.run()` with an import string such as `app.main:app`. `fastapi dev` defaults to `--host 127.0.0.1` and `--reload`, so a file watcher restarts the server on every code change; with FastAPI 0.143's CLI it also sets `FASTAPI_ENV=development` unless the variable is already set. `fastapi run` defaults to `--host 0.0.0.0`, reload off, leaves `FASTAPI_ENV` alone, and is the only one of the two with `--workers`. Both use port 8000 unless `--port` or the `PORT` variable says otherwise, and both find the app the same way: a path or `--entrypoint`, then `[tool.fastapi] entrypoint` in pyproject.toml, then auto-discovery. Production and container images use `fastapi run`: reload costs CPU and stability, and a loopback bind is unreachable from outside a container.
go deeper
Know the two commands by heart: dev for your machine with reload on localhost, run for servers and containers on all interfaces. Mention that both start Uvicorn.
Explain the default table (host, reload, workers, FASTAPI_ENV) and the order in which the CLI resolves the app: path or --entrypoint, then pyproject.toml, then auto-discovery.
Diagnose the classic container failure: a healthy process bound to loopback that no published port can reach. Pin the entrypoint so every environment imports the same app.
Standardise one start command across environments, pinned in pyproject.toml, so laptops, images and tooling never disagree about which app object is served.
## Two commands, one server The `fastapi` command comes from the **fastapi-cli** package, which `pip install "fastapi[standard]"` pulls in. A bare `pip install fastapi` still installs a `fastapi` entry point, but it only prints that you should install `"fastapi[standard]"` and raises an error. Once the CLI is present, `fastapi dev` and `fastapi run` do the same three things: 1. resolve an **import string** such as `main:app` that points at your `FastAPI` instance; 2. print where the server and its `/docs` page will be; 3. call `uvicorn.run()` with that import string and the options you passed. Neither command is a different server. **Uvicorn**, the ASGI server, does the serving in both cases. The two commands are two sets of defaults, and those defaults are the whole difference. ## The defaults side by side | Setting | `fastapi dev` | `fastapi run` | |---|---|---| | `--host` | `127.0.0.1` | `0.0.0.0` | | `--port` | `8000`, or the `PORT` variable | `8000`, or the `PORT` variable | | `--reload` | on | off | | `--workers` | not offered | optional | | `FASTAPI_ENV` | set to `development` if unset | left as it is | What each row means: - **Host.** `127.0.0.1` is the **loopback** address: only programs on the same machine can connect to it. `0.0.0.0` means every network interface the machine has, which a server in a container or on a VM needs so that traffic arriving from outside reaches it. - **Reload.** With reload on, Uvicorn runs a reloader process that watches the project directory and restarts the server process whenever code changes. FastAPI's docs call this resource-intensive and possibly less stable, and say to use it only in development. - **Workers.** Only `fastapi run` has a `--workers` option. `fastapi dev --workers 2` stops with "No such option: --workers". - **`FASTAPI_ENV`.** With FastAPI 0.143's CLI (fastapi-cli 0.0.32), `fastapi dev` sets `FASTAPI_ENV=development` before importing your app and keeps any value that is already set. `fastapi run` leaves the variable unchanged, so set it yourself if startup code needs to detect production. `fastapi run --reload` exists, and `fastapi dev --host 0.0.0.0` exists, so each default can be overridden. The point of the two commands is that the default you get without thinking is the right one for that setting. ## How the CLI finds the app Both commands resolve the app in the same order: 1. a **path argument** (`fastapi run app/main.py`) with an optional `--app NAME`, or the **`--entrypoint`** option (`-e app.main:app`); the CLI refuses to combine `--entrypoint` with a path or `--app`; 2. the **`entrypoint`** key under `[tool.fastapi]` in the `pyproject.toml` of the **current working directory**; 3. **auto-discovery**: it tries `main.py`, `app.py`, `api.py`, `app/main.py`, `app/app.py` and `app/api.py`, then looks in the module for an object named `app` or `api`, and otherwise takes the first `FastAPI` instance it finds. ```toml [tool.fastapi] entrypoint = "app.main:app" ``` When it auto-discovers, the CLI prints the `[tool.fastapi]` snippet that would pin what it found. The docs recommend pinning it, because other tools, such as FastAPI's editor extension, read the same key and cannot guess what you typed on the command line. ## Why `fastapi dev` fails in a container A container has its own network stack. A port you publish from the host forwards traffic to the container's network interface, not to its loopback address. A server bound to `127.0.0.1` inside the container therefore never sees that traffic. The usual symptom is that the container is running and its logs look normal, but every request from outside fails to connect. On top of that, reload would watch files in an image that never changes, spending CPU for nothing. `fastapi run` has the right host and no watcher. That is why FastAPI's Dockerfile examples end in `CMD ["fastapi", "run", "app/main.py", "--port", "80"]`. ## Habits worth keeping - Use `fastapi dev` on your laptop and `fastapi run` everywhere else, including staging. - Pin `[tool.fastapi] entrypoint` so local runs, scripts and editor tooling resolve the same app. - Read `FASTAPI_ENV` in startup code only if your deployment sets it; `fastapi run` will not. - Pass `--port` or set `PORT` when a platform tells you which port to listen on. - Keep `fastapi dev` out of Dockerfiles and service definitions; if you want reload while developing inside a container, override the command in your local setup only, so the image itself always starts `fastapi run`.
- What happens if you run `fastapi run app/main.py --entrypoint app.main:app`?The FastAPI CLI stops with "Cannot use --entrypoint together with path or --app arguments" and exits with code 1. A path argument (with optional `--app`) and `--entrypoint` are two ways of naming the same thing, so the CLI accepts one or the other. If you pass neither, it falls back to `[tool.fastapi] entrypoint` in pyproject.toml, then to auto-discovery.
- Why can a `[tool.fastapi] entrypoint` that works on your laptop be ignored in a container?The FastAPI CLI reads `pyproject.toml` from the current working directory only. If the image's working directory does not contain that file, or the file was never copied in, the CLI falls back to auto-discovery and may fail with "Could not find a default file to run". Either copy pyproject.toml into the working directory or pass a path, as FastAPI's Dockerfile examples do with `app/main.py`.
- Can you get auto-reload from `fastapi run`, and can you combine it with workers?`fastapi run --reload` turns the file watcher on while keeping the `0.0.0.0` bind. Combined with `--workers`, Uvicorn logs that the workers flag is ignored when reloading is enabled and runs one reloading server process. The CLI's help calls the two options mutually exclusive, but in practice reload wins and you get no worker processes.
- fastapi dev and fastapi run start two different servers
- fastapi dev is fine in production if you also pass --workers
- fastapi run listens only on localhost unless you add --host
- fastapi run sets FASTAPI_ENV to production for you
- A plain pip install fastapi gives you a working fastapi command
- Auto-discovery wins over the entrypoint set in pyproject.toml
Assumes FastAPI 0.143 installed with its standard extra, which requires fastapi-cli 0.0.32; that CLI release is the first in which fastapi dev sets FASTAPI_ENV.