What are Uvicorn and Gunicorn, and how do they work together for FastAPI?
Uvicorn is an ASGI server. It owns the event loop, parses HTTP (and WebSocket) traffic, and translates each connection into ASGI calls that your FastAPI application handles. Run on its own, a Uvicorn process is a complete server. It accepts connections, runs your app's lifespan startup and shutdown hooks, and serves requests concurrently on one event loop.
Gunicorn is a pre-fork process manager. A master process binds the listening socket, forks a configured number of child processes, and then supervises them. It restarts children that crash or stop responding within the timeout, and it handles signals for reloads and graceful shutdown. Gunicorn was built around WSGI, but its worker class is pluggable. That lets it host Uvicorn's worker implementation instead of a synchronous one.
In the combined setup, Gunicorn never touches a request. Each child process runs Uvicorn's event loop and protocol code, so every request is parsed and dispatched by the same Uvicorn code as in a standalone deployment. Gunicorn only manages the lifecycle of those processes.
This is why the decision is not mainly about raw throughput. The request path is the same Uvicorn code either way. The real question is who supervises worker processes:
- Gunicorn's master, inside one container or VM, or
- Your container orchestrator, which runs one Uvicorn process per container and restarts or replaces containers itself.
Check where the Gunicorn worker class for Uvicorn lives in the versions you have installed. It originally shipped inside the Uvicorn package, and it has since been moved into a separate package. Import paths in older guides may not match your environment.
A) Gunicorn master supervises B) Orchestrator supervises
+-------------------------------+ +-------------------------------+
| Container / VM | | Cluster |
| +---------------------------+ | | +---------------------------+ |
| | Gunicorn master | | | | Container orchestrator | |
| | binds socket, forks, | | | | restarts / replaces | |
| | restarts children, | | | | containers, scales | |
| | handles signals | | | | replica count | |
| +---+---------+---------+---+ | | +---+---------+---------+---+ |
| |fork |fork | | | | | | |
| v v v | | v v v |
| +-------+ +-------+ +-------+ | | +-------+ +-------+ +-------+ |
| |Uvicorn| |Uvicorn| |Uvicorn| | | |Uvicorn| |Uvicorn| |Uvicorn| |
| |worker | |worker | |worker | | | |process| |process| |process| |
| |process| |process| |process| | | |own ctr| |own ctr| |own ctr| |
| +---+---+ +---+---+ +---+---+ | | +---+---+ +---+---+ +---+---+ |
| ^ ^ ^ | | ^ ^ ^ |
| accept() on shared socket | | traffic routed per container |
+-------------------------------+ +-------------------------------+
Both: HTTP -> Uvicorn protocol code -> ASGI -> FastAPI app
Gunicorn manages process lifecycle only; it never parses requests.
Uvicorn serves every request in both models; the difference is whether Gunicorn's master forks and restarts Uvicorn workers inside one container or VM, or the orchestrator runs one Uvicorn process per container and replaces containers itself.
How does it work?
The sequence differs only in who starts and watches the processes. The request path stays the same.
Startup with Gunicorn and Uvicorn workers:
- The Gunicorn master reads its config, binds the listening socket, and (if
--preloadis set) imports your application. - The master forks N children. Each child loads the Uvicorn worker class, which creates an asyncio event loop and imports the app if it was not preloaded.
- Each worker runs the ASGI lifespan startup event, so FastAPI's startup code runs once per worker.
- All workers call
accept()on the same inherited socket. The kernel hands each new connection to one of them, and from then on that connection belongs to that worker.
Request handling in a worker: Uvicorn reads bytes from the connection, parses the HTTP request, builds an ASGI scope dictionary, and calls your FastAPI app with receive and send callables. FastAPI routes the request, runs dependencies and the endpoint, and sends the response back through send. Uvicorn writes it to the socket. async def endpoints run on the event loop. Plain def endpoints run in a threadpool.
Supervision: Each Gunicorn worker periodically signals that it is alive by updating a temporary file the master watches. If a worker stays silent longer than --timeout, the master kills and replaces it. If a worker exits, the master forks a new one. Signals sent to the master (SIGTERM, SIGHUP, SIGTTIN/SIGTTOU to change the worker count) are translated into actions on the children.
Startup with Uvicorn alone: A single uvicorn process binds the socket, imports the app, runs lifespan startup and serves requests. Nothing inside the container restarts it if it dies. That job falls to the orchestrator or init system. With --workers N, Uvicorn starts a parent process that spawns N child server processes sharing the socket and restarts them according to the behavior of your installed version.
How do the three FastAPI deployment shapes compare?
| Shape | Restarts a crashed worker | Handles signals | Scales by |
|---|---|---|---|
| One Uvicorn process per container | Orchestrator restarts the container | Uvicorn, as PID 1 or behind a minimal init | Adding pods |
uvicorn --workers N |
Uvicorn's parent process | Uvicorn's parent process | Pods × N |
| Gunicorn + Uvicorn workers | Gunicorn master | Gunicorn master | Pods × N |
Single process: uvicorn app.main:app --host 0.0.0.0 --port 8000. SIGTERM reaches the server directly. Per-pod metrics describe one process, and CPU and memory limits map onto exactly one interpreter. The costs are more pods, a runtime and imported libraries duplicated in every pod, and slower recovery: a crash means a container restart, not a quick respawn inside the pod.
Uvicorn workers: uvicorn app.main:app --workers 4. One package and no extra config. Its supervision has historically been thinner than Gunicorn's and has changed across releases, so test crash and timeout behavior on the version you have installed.
Gunicorn master: gunicorn app.main:app -k <UvicornWorker class> -w 4 -b 0.0.0.0:8000. The master adds:
- worker timeouts (
--timeout) that kill hung workers - recycling with
--max-requestsand--max-requests-jitter, so workers don't all restart at once - graceful reload on SIGHUP
--preloadto import the app once before forking
This second supervision layer can conflict with the orchestrator. A healthy master keeps the pod "running" while its workers crash-loop, so liveness probes must check request handling, not process existence.
#!/usr/bin/env bash
set -euo pipefail
SHAPE="${SHAPE:-single}" # single | uvicorn-workers | gunicorn
WORKERS="${WORKERS:-4}"
case "$SHAPE" in
single)
# One interpreter per container: the orchestrator restarts it and scales pods.
exec uvicorn app.main:app --host 0.0.0.0 --port 8000
;;
uvicorn-workers)
# Uvicorn's parent process supervises N workers.
# Test crash and hang behavior on your installed version.
exec uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers "$WORKERS"
;;
gunicorn)
# Gunicorn master supervises N Uvicorn workers.
# Worker class: uvicorn.workers.UvicornWorker in older Uvicorn releases,
# or uvicorn_worker.UvicornWorker from the separate uvicorn-worker package.
exec gunicorn app.main:app \
-k uvicorn.workers.UvicornWorker \
-w "$WORKERS" \
-b 0.0.0.0:8000 \
--timeout 30 \
--graceful-timeout 25 \
--max-requests 5000 \
--max-requests-jitter 500
# --timeout: kill workers that stop responding to the master.
# --max-requests plus jitter: recycle workers at staggered points, not all at once.
# Add --preload to import the app once in the master before forking.
# Graceful reload from inside the pod: kill -HUP 1
;;
*)
echo "unknown SHAPE: $SHAPE" >&2
exit 64
;;
esac
This container entrypoint launches a single Uvicorn process, Uvicorn's --workers mode or a Gunicorn master with Uvicorn workers, using exec so the chosen server receives signals as PID 1.
How many workers should a FastAPI service run?
The 2 × cores + 1 rule comes from Gunicorn's guidance for synchronous workers. A sync worker handles one request at a time, so you oversubscribe cores to keep the CPU busy while some workers block on I/O. An async Uvicorn worker does not block that way. A single event loop can hold hundreds of concurrent connections while it waits on the database or upstream APIs. Adding workers therefore does not add concurrency in the sync sense. It adds CPU parallelism, because each process has its own GIL. That parallelism only helps when request handling actually spends time on the CPU: serialization, validation, templating, compression.
Containers introduce a separate trap. os.cpu_count() reports the host's CPUs, not the cgroup CPU quota. A config that computes workers from it can start 33 processes on a 64-core node inside a pod limited to two CPUs. Those workers compete for the same quota, so the kernel throttles the container, and each process holds its own copy of the application in memory, which pushes the pod toward its memory limit.
Set the worker count explicitly from the CPU limit you configured. The snippet below reads it from an environment variable instead of probing the machine. Start with roughly one worker per available CPU, then load-test with realistic payloads and concurrency. Once the worker count passes the CPU limit, extra workers add context switching and memory overhead without adding throughput.
import os
_raw = os.environ.get("WEB_CONCURRENCY", "1")
try:
workers = int(_raw)
except ValueError:
raise SystemExit(f"WEB_CONCURRENCY must be an integer, got {_raw!r}")
if workers < 1:
raise SystemExit("WEB_CONCURRENCY must be >= 1")
worker_class = "uvicorn.workers.UvicornWorker"
bind = os.environ.get("BIND", "0.0.0.0:8000")
timeout = 30
def on_starting(server):
server.log.info("Starting with %d worker(s) from WEB_CONCURRENCY", workers)
A Gunicorn config for FastAPI that takes the worker count from the WEB_CONCURRENCY environment variable, set to match the container's CPU limit, instead of computing it from os.cpu_count(), which reports host CPUs.
Budgeting memory, connections and startup cost per worker
Each worker is a separate Python interpreter with its own copy of your application, loaded models, and in-process caches. A 200 MB model loaded at import time costs 200 MB per worker, not 200 MB per container.
Gunicorn's --preload imports the app once in the master and forks workers from it, so pages start out shared via copy-on-write. The savings are only partial. CPython stores reference counts inside each object, so merely touching a shared object writes to its page and gives that worker a private copy. Preloading also has two other costs:
- Database connections, client sessions, or threads created before the fork must not be shared with the children. Create them per worker, after the fork.
- Preloaded code only changes on a full master restart, not a worker reload.
Illustrative estimate (assumed numbers, not a benchmark)
| Budget | Formula | Assumed inputs | Result | Limit |
|---|---|---|---|---|
| Container memory | per-worker RSS × workers + master | 350 MB × 4 + 60 MB | 1,460 MB | 1,536 MB container limit |
| DB connections | pool size × workers × replicas | 10 × 4 × 6 | 240 | 200 allowed by the database |
The memory budget leaves about 5% headroom, which is one traffic spike away from an OOM kill. The connection budget is already over the limit before you count pool overflow, migrations, or admin sessions.
--max-requests (with --max-requests-jitter) recycles workers to cap slow leaks. It does not fix them, though. It hides the cause and adds cold-start latency spikes each time a fresh worker loads the app. Every worker you add raises your node size and database tier. Every masked leak costs debugging time later, when the leak outgrows the recycle interval.
When should you avoid adding more workers?
Adding workers is the wrong fix when the real problem is code that blocks the event loop. A synchronous call inside an async def endpoint, such as requests.get(), a sync database driver, or a large JSON parse, holds the loop for its full duration. Every other request on that worker waits behind it. More workers spread the stall across processes and make it less visible, but the cause remains.
The before/after example shows the fix. In the before version, an async def handler calls a blocking HTTP client. In the after version, the handler awaits an async client or becomes a plain def. FastAPI runs plain def endpoints in a threadpool, but that pool is size-limited, so slow sync handlers can still queue up.
Under Gunicorn, a blocked loop has a sharper failure. The worker cannot send its heartbeat, so the arbiter kills it mid-request after --timeout. The timeout cannot tell a deadlock from a busy loop. It can also kill legitimate long requests, streaming responses, and slow uploads.
Every worker also duplicates per-process state:
- Lifespan hooks run once per worker, so you get N database pools and N copies of any scheduler. Scheduled jobs then fire N times.
- In-memory caches, rate limiters, sessions and WebSocket registries are not shared. A client rate-limited on one worker is fresh on the next.
- Metrics libraries need a multiprocess mode or per-process scraping. Otherwise counters reflect whichever worker answered the scrape.
Moving this state to an external store fixes correctness, but it adds network latency to each request and a new dependency that can fail.
import os
import httpx
import requests
from fastapi import FastAPI
app = FastAPI()
UPSTREAM = os.environ["UPSTREAM_URL"]
@app.get("/before/items/{item_id}")
async def get_item_blocking(item_id: int):
resp = requests.get(f"{UPSTREAM}/{item_id}", timeout=5)
return resp.json()
@app.get("/after/items/{item_id}")
async def get_item_async(item_id: int):
async with httpx.AsyncClient(timeout=5) as client:
resp = await client.get(f"{UPSTREAM}/{item_id}")
return resp.json()
@app.get("/after-sync/items/{item_id}")
def get_item_threaded(item_id: int):
resp = requests.get(f"{UPSTREAM}/{item_id}", timeout=5)
return resp.json()
A blocking requests.get() inside an async def endpoint stalls the worker's event loop, and the two fixes are awaiting an async client or declaring a plain def so FastAPI runs it in its threadpool.
How do you get graceful shutdown and zero-downtime deploys right?
Kubernetes and most other orchestrators send SIGTERM to PID 1 in the container, wait for the termination grace period, then send SIGKILL. The process that receives SIGTERM decides whether shutdown is graceful. If you start the server with a shell-form entrypoint, PID 1 is /bin/sh, which usually does not forward the signal. The server is then killed mid-request when the grace period expires. Use exec-form entrypoints, exec the server from wrapper scripts, or run a minimal init that forwards signals.
With Gunicorn, the master receives SIGTERM, stops accepting connections, and signals its workers. Each Uvicorn worker finishes in-flight requests until Gunicorn's graceful_timeout expires, then the master kills it. Running Uvicorn alone, the process drains directly. Recent releases expose a graceful-shutdown timeout option, but check your installed version for the exact name. Long-lived WebSockets do not end on their own, so the timeout must cover the reconnect behavior your clients expect.
Removing a pod from load balancer endpoints happens asynchronously. Use a preStop hook that marks the readiness endpoint as failing and then sleeps briefly, so routing stops before SIGTERM arrives. The hook's time counts against the grace period.
Illustrative estimate (assumed numbers, not a benchmark):
grace period ≥ preStop delay + graceful timeout + margin
With an assumed 5 s delay, 20 s timeout and 5 s margin, the grace period should be at least 30 s.
The settings named above (graceful_timeout, terminationGracePeriodSeconds, preStop, readiness probe fields) may differ in name or behavior between releases. Verify them against your installed versions.
Who should use it?
Uvicorn alone (one process per container) suits teams that deploy FastAPI on Kubernetes or a similar orchestrator with resource limits, readiness and liveness probes, and horizontal scaling. The platform already restarts failed containers and routes around unhealthy ones, so one server process per container is the simplest model to reason about. Uvicorn alone, with --reload, is also the normal choice for local development.
uvicorn --workers N suits small deployments that want to use a few CPU cores on one host without adding a second package, and where the team has tested how the installed Uvicorn version handles crashed or hung workers.
Gunicorn with Uvicorn workers suits teams that run FastAPI on VMs or bare metal without an orchestrator, or that already operate Gunicorn for WSGI services and want the same timeouts, worker recycling, --preload and signal handling for ASGI apps. It also fits services with CPU-heavy request handling that need several processes per host and want a mature supervisor managing them.
Neither multi-worker shape is a good fit for teams whose main problem is blocking code in async endpoints, or whose app keeps state in process memory (caches, rate limiters, WebSocket registries, schedulers) that has not been moved to a shared store. Fix those first, then add workers.
What are the alternatives?
The choice is not limited to Uvicorn and Gunicorn. Alternatives fall into two groups.
Other ASGI servers can serve a FastAPI app in place of Uvicorn:
- Hypercorn is an ASGI server that supports HTTP/2 and can run on asyncio or Trio. It is worth evaluating if you need HTTP/2 served directly by the Python process.
- Daphne is the ASGI server developed alongside Django Channels. It runs any ASGI app, though it is most commonly used in Django projects.
- Granian is an ASGI server written in Rust with Python bindings, with its own worker and process management.
Each has its own options for workers, timeouts and graceful shutdown. Check their behavior against the same concerns covered here (signal handling as PID 1, per-worker state, connection budgets) before switching. Do not assume one is faster for your workload without load-testing it.
Other process supervisors can replace Gunicorn's role while Uvicorn keeps serving requests:
- The container orchestrator restarts containers, scales replicas and gates traffic through probes.
- systemd can run one or more Uvicorn units on a VM, restart them on failure, and manage logs and ordering. Socket activation and templated units let you run several instances on one host.
- supervisord and similar process managers can keep Uvicorn processes running on hosts without systemd.
With these supervisors, you run several independent Uvicorn processes, each bound to its own port or a shared socket, behind a reverse proxy or load balancer, instead of one master forking workers.
Which should you choose: Uvicorn alone or Gunicorn with Uvicorn workers?
The choice mostly follows from what already supervises your processes. If something outside Python restarts crashed processes, routes traffic only to healthy instances and delivers shutdown signals, a second supervisor inside the container duplicates that job.
| Environment | Recommended shape | Why |
|---|---|---|
| Kubernetes or similar, with resource limits and health checks | One Uvicorn process per pod, or a small fixed worker count; scale with replicas | The platform restarts failed containers, probes gate traffic, and autoscaling adds replicas. One process per pod keeps limits and metrics easy to interpret. |
| VM or bare metal, no external supervisor | Gunicorn with Uvicorn workers | Gunicorn's master restarts dead workers and handles signals, filling a gap nothing else covers. |
| VM with systemd | Uvicorn under systemd | systemd provides restarts, ordering and logging without an extra process layer. |
Matching the process model to the supervision you already have saves engineering time. Restarts, scaling and signal handling each live in one place. When a worker dies, there is one log stream and one restart policy to check, not two. On-call engineers do not have to work out whether Gunicorn or the kubelet killed a process, or which timeout fired first.
Before you fix any numbers:
- Set CPU and memory limits for each container or unit.
- Set the worker count explicitly instead of deriving it from detected cores.
- Size database and HTTP connection pools per worker, then multiply by total processes.
- Align shutdown timeouts across the server, the supervisor and the load balancer.
- Run a load test with realistic payloads.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to uvicorn vs gunicorn fastapi, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.