skip to content

What does `fastapi run --workers 4` start for a FastAPI app, and how do its Uvicorn worker processes share the incoming work?

level: middleimportance: must knowfreq 60%

answer

  1. a supervisor plus N copies
  2. one listening socket, many acceptors
  3. spawned, not forked
  4. dead workers come back
  5. WEB_CONCURRENCY when the flag is absent

basics

~20 s

A Uvicorn parent process binds the port once and spawns four worker processes; each imports the FastAPI app, runs its own lifespan and accepts connections from the shared socket. The parent supervises and restarts workers but never handles requests.

solid answer

~40 s

`fastapi run --workers 4` calls `uvicorn.run()` with `workers=4`, so Uvicorn starts a **parent** that binds the listening socket and then starts four child processes with Python's `spawn` start method. Each child imports the app from the import string, runs the `lifespan` startup, and accepts connections on the socket it inherited, so the operating system decides which worker gets each connection; the parent never touches request bytes. In FastAPI 0.143's setup (Uvicorn 0.54) the parent pings its children, kills a hung one, starts a replacement for one that dies, and on `SIGHUP` replaces them one at a time. Without `--workers`, Uvicorn takes the count from `WEB_CONCURRENCY`, else 1, and with `--reload` it ignores workers altogether.

code

console · 14 lines
console
$ fastapi run --workers 2
...
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started parent process [46204]
INFO:     Started server process [46208]
INFO:     Waiting for application startup.
INFO:     Started server process [46207]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Application startup complete.
INFO:     Child process [46207] died
INFO:     Started server process [49006]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

go deeper

for a junior

Remember the shape: one parent, N worker processes, each running a full copy of the FastAPI app.

for a middle

Explain spawn versus fork, the shared listening socket, per-connection distribution, and why lifespan startup and module state exist once per worker.

for a senior

Use the supervisor deliberately: SIGHUP for rolling restarts, the startup-failure stop, WEB_CONCURRENCY for the count, and the reload-ignores-workers trap.

for a principal

Treat in-process state as per-worker by policy, so caches, rate limits and connection registries move to shared stores before anyone raises the worker count.

## What the command starts `fastapi run` hands its options to `uvicorn.run()` with an import string such as `app.main:app`. With `--workers 4`, Uvicorn does not serve requests in the process you started. Instead it builds this tree: - one **parent process**, logged as `Started parent process [PID]`; - four **worker processes**, each logged as `Started server process [PID]`, each followed by its own `Waiting for application startup.` and `Application startup complete.` Uvicorn starts the workers with the `spawn` start method of Python's `multiprocessing`, not with a pre-fork. A spawned process is a fresh interpreter: it imports your module from the import string and builds the app itself. That is why Uvicorn insists on an import string for workers: `uvicorn.run(app_object, workers=2)` logs "You must pass the application as an import string to enable 'reload' or 'workers'." and exits. The FastAPI CLI always passes a string, so you never hit this through `fastapi run`. ## The parent supervises, it does not balance The parent's jobs, as Uvicorn 0.54 implements them: 1. **Bind once.** It opens the listening socket and hands the same socket to every worker. 2. **Watch.** Every half second it checks that each child is alive and answers a ping within `--timeout-worker-healthcheck` (5 seconds by default); a child that does not answer is killed. 3. **Replace.** A worker that dies is logged as `Child process [PID] died` and a new one is started in its slot. A worker that fails *before* it starts serving makes the parent stop altogether, since a broken import or bind would fail the same way on every retry. 4. **Obey signals** (on platforms with POSIX signals). `SIGHUP` replaces the workers one at a time, each new one made ready before the old one is retired. `SIGTTIN` adds a worker and `SIGTTOU` removes one. 5. **Shut down.** On `SIGTERM` or `SIGINT` it terminates the children, each of which runs its lifespan shutdown, and then exits. What the parent does **not** do is route requests. Every worker accepts connections on the shared socket itself, so the operating system picks which waiting worker gets each new connection. Distribution is per **connection**, not per request: a client that keeps a connection alive keeps talking to the same worker. ## Every worker is a whole copy of the app Because each worker imports the app on its own, each one has: - its own `lifespan` run, so startup code and anything yielded as lifespan state exist four times; - its own memory, so module-level caches, counters and in-process locks are per worker and never agree with each other; - its own event loop and its own thread pool for `def` endpoints. A WebSocket client connected to one worker is invisible to the other three, which is why a per-process registry of connections stops working the day workers are added. Anything that must be shared across workers belongs in an external store. How much memory those copies cost is a sizing question of its own. ## How the worker count is chosen | Invocation | Worker processes | |---|---| | `fastapi run --workers 4` | 4 | | `fastapi run` with `WEB_CONCURRENCY=3` set | 3 | | `fastapi run` with nothing set | 1, served without a parent | | `fastapi run --reload --workers 4` | 1 reloading process, with a warning that workers are ignored | | `fastapi dev --workers 4` | rejected: `fastapi dev` has no `--workers` | The `fastapi run` help text calls `--workers` and `--reload` mutually exclusive, but nothing stops you from passing both: Uvicorn logs `"workers" flag is ignored when reloading is enabled.` and runs the reloader. ## The same thing with `uvicorn` directly `uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4` builds exactly the same tree, because `fastapi run` is a thin layer over it. Running Uvicorn yourself is worth it only for the options the FastAPI CLI does not pass through, such as `--limit-max-requests` or `--timeout-graceful-shutdown`. ## What to say in an interview - Workers give you **parallelism across CPU cores**, which one Python process cannot, and a supervisor that restarts crashed processes. - They multiply everything a process holds, so they are sized by memory as much as by cores. - The parent is a process manager, not a load balancer; balancing between machines or containers is somebody else's job. - On a container platform that already runs several replicas, workers inside each container are usually redundant, and one process per container is the common default there.

  • Why does a Uvicorn worker that fails during startup stop the whole server instead of being restarted?
    Uvicorn's parent treats a child that exits before it starts serving as a configuration problem: a failed import, a lifespan startup that raised, a TLS or socket error. Restarting it would fail the same way forever, so the parent logs that the child failed to start and shuts down. Only workers that die after serving are replaced, which lets an orchestrator or service manager see the failure.
  • How do you roll new code into a running `fastapi run --workers 4` without dropping requests?
    Send `SIGHUP` to the Uvicorn parent. It starts a replacement worker, waits until it is ready, then terminates one old worker, and repeats for each slot; the fresh workers import the new code from disk. If a replacement is not ready in time, the parent keeps the old worker and aborts the restart. This works only on platforms with POSIX signals.
  • Does each Uvicorn worker keep its own thread pool for a FastAPI app's `def` endpoints?
    Yes. The thread pool that runs `def` path operations and dependencies lives inside each worker's event loop, so four workers mean four pools of the default size. Tuning the pool is per process, which is one reason the worker count and thread-pool settings have to be decided together.

The parent is a shift supervisor who opens the shop door once, hires four clerks and replaces any who walk out, but never serves a customer; customers queue at the one door and whichever clerk reaches it first takes the next one.

  • The Uvicorn parent receives each request and forwards it to a worker
  • Workers are threads that share the app's memory
  • Lifespan startup runs once in the parent before workers start
  • A crashed worker stays dead until the whole server restarts
  • --reload together with --workers gives you several reloading workers
  • Without --workers, Uvicorn starts one worker per CPU core

Assumes FastAPI 0.143 served by Uvicorn 0.54, whose parent process restarts dead workers and handles SIGHUP, SIGTTIN and SIGTTOU; older Uvicorn releases did not restart dead workers.