What do Uvicorn and Gunicorn each do in a FastAPI deployment?

The real decision is where process supervision should live. Something has to start worker processes, restart them when they crash, and shut them down cleanly on deploy. That job can belong to Gunicorn, to Uvicorn's own multi-process mode, or to your orchestrator.

Uvicorn: the ASGI server

Uvicorn runs your FastAPI application. It parses HTTP (and WebSocket) traffic off the socket, translates each connection into ASGI calls, and drives the asyncio event loop that executes your async def handlers. One Uvicorn process means one event loop on one CPU core. Concurrency within that process comes from interleaving coroutines at await points, not from threads or extra processes. Uvicorn can spawn several worker processes itself, but its supervision features are deliberately modest.

Gunicorn: the process manager

Gunicorn is a pre-fork server built for WSGI. A master process binds the listening socket, forks workers that share it, and monitors them. It replaces workers that die or stop responding within the timeout, and it handles Unix signals for graceful reloads and scaling the worker count. Gunicorn does not speak ASGI natively. To host FastAPI, you point it at a Uvicorn worker class. Gunicorn then manages the processes, and each worker runs a Uvicorn event loop inside. The import path for that worker class has changed across Uvicorn releases, so check the documentation for the version you have installed rather than copying an older example.

In this pairing, Uvicorn serves requests and Gunicorn supervises the processes. If Kubernetes or systemd already handles supervision, you may not need Gunicorn.

                      HTTP / WebSocket clients
                                  |
                                  v
          ---- shared listening socket (bound by master) ----
                 |                |                |
                 | accept         | accept         | accept
                 v                v                v
          +--------------+ +--------------+ +--------------+
          |Uvicorn worker| |Uvicorn worker| |Uvicorn worker|
          | HTTP parsing | | HTTP parsing | | HTTP parsing |
          | asyncio loop | | asyncio loop | | asyncio loop |
          |      | ASGI  | |      | ASGI  | |      | ASGI  |
          |      v       | |      v       | |      v       |
          | FastAPI app  | | FastAPI app  | | FastAPI app  |
          | 1 loop/core  | | 1 loop/core  | | 1 loop/core  |
          +--------------+ +--------------+ +--------------+
                 ^                ^                ^
                 | fork, monitor  |                |
                 +----------------+----------------+
                                  |
         +------------------------+-----------------------+
         | Gunicorn master (process supervision)          |
         | - binds socket, forks workers                  |
         | - replaces dead or timed-out workers           |
         | - signals: graceful reload, scale workers      |
         +------------------------------------------------+

   Supervision could instead live in Uvicorn's own multi-process
   mode or in an orchestrator such as Kubernetes or systemd.

In the Gunicorn-plus-Uvicorn topology, the Gunicorn master binds the socket and supervises worker processes, while each Uvicorn worker parses HTTP and runs one asyncio event loop that calls the FastAPI app over ASGI.

How does it work, from startup to response?

The lifecycle is the same in every topology. What changes is which process performs each step.

Startup

  1. The supervisor binds the socket. Under Gunicorn, the master opens the listening socket before it creates any workers. With uvicorn --workers N, Uvicorn's parent process does the same. With a single Uvicorn process, that process binds the socket itself.
  2. Workers are created. Gunicorn forks its workers from the master, so they inherit the already-open socket. If preload_app is set, the application module was imported in the master before the fork. Otherwise each worker imports it after the fork.
  3. Each worker builds its own event loop. The loop belongs to that process only. Nothing about it is shared with other workers.
  4. Lifespan startup runs. Uvicorn sends the ASGI lifespan startup event, and FastAPI runs your lifespan handler, which opens database pools, HTTP clients and similar resources. A worker starts accepting connections only after this step completes.

Handling a request

  1. The kernel picks a worker. All workers wait to accept on the same socket, and the kernel gives each new connection to one of them. A connection stays on that worker for its whole life, including every request sent over it with keep-alive.
  2. Uvicorn parses the bytes. It uses httptools when installed and falls back to h11 otherwise. Uvicorn turns the request line and headers into an ASGI scope dictionary that holds the method, path, headers, client address and scheme.
  3. The ASGI call. Uvicorn calls app(scope, receive, send). receive yields body chunks and disconnect events. send accepts the response start (status and headers) and the response body.
  4. FastAPI handles routing. Starlette's router matches the path. FastAPI resolves dependencies, validates input, and either awaits your async def handler on the loop or runs your def handler in the threadpool. It then serializes the return value.
  5. The response goes out. Uvicorn writes the bytes back to the socket. With keep-alive, the connection then waits for the next request until the keep-alive timeout closes it.

Supervision and shutdown

While the workers run, the supervisor watches them. A Gunicorn worker sends a periodic heartbeat to the master. If the heartbeat stops for longer than --timeout, the master kills and replaces that worker, and it also replaces any worker that exits. On SIGTERM, the supervisor tells each worker to stop accepting new connections and finish its in-flight requests. Each worker then runs lifespan shutdown and exits. In the single-process topology there is no supervisor inside the container, so the orchestrator handles this role by restarting the container and sending SIGTERM.

Which production topology fits your platform?

The right choice depends on what already supervises your processes. Running a second supervisor under an orchestrator adds overhead and does little useful work.

Topology Suits Avoid when
One Uvicorn process per container Kubernetes, ECS, or any platform with replicas, health probes and restarts You pay per container and memory density matters more than isolation
uvicorn --workers N VMs or single containers where you want several cores used with minimal config You need per-worker timeouts or recycling
Gunicorn with Uvicorn workers VMs under systemd, legacy hosts, apps with slow memory leaks An orchestrator already restarts and health-checks each process

One process per container gives the orchestrator a one-to-one view: a failed probe means one dead worker, and the platform replaces it. You scale on a single axis, replica count.

Multi-worker pods pack resources more densely because workers share a container's memory overhead. The cost is coarser health signals. A pod can pass its probe while one worker is wedged. Scaling also becomes two-dimensional, since you now tune both workers per pod and pod count.

Gunicorn adds three things: a timeout that kills hung workers, max-requests with jitter to recycle leaky processes without restarting them all at once, and signal-based graceful reloads. It also adds a dependency and more configuration to maintain, and it duplicates supervision that Kubernetes already provides.

If most handlers call blocking libraries, consider plain def endpoints on FastAPI's threadpool, or a sync WSGI stack. Either is usually more honest than forcing async.

What are the alternatives?

The choice isn't strictly "Uvicorn or Gunicorn". You can replace the server, the supervisor, or the programming model.

Other ASGI servers

FastAPI depends only on the ASGI interface, not on Uvicorn, so any compliant ASGI server can run it.

  • Hypercorn is an ASGI server that supports HTTP/2, and it can also run on the trio event loop as well as asyncio. Consider it when you need HTTP/2 served by the Python process itself rather than terminated at the proxy.
  • Daphne came out of the Django Channels project. It is a natural fit when you already operate Channels, but it is a less common choice for a standalone FastAPI service.

Changing the server changes the CLI flags, the configuration names, and how you set proxy-header trust and timeouts. Don't assume Uvicorn's options carry over. Read that server's documentation and repeat your load test.

Other supervisors

Supervision can live outside Python:

  • The orchestrator. Kubernetes, ECS and similar platforms restart failed containers, run health probes and scale replicas. Paired with a single Uvicorn process per container, this is usually the simplest setup.
  • systemd. On a VM, a systemd unit can run Uvicorn directly and restart it on failure, with resource limits set in the unit file. For one process per host, or one unit per port behind a local proxy, this can replace Gunicorn.
  • Uvicorn's own --workers. This sits between the two: a single command that uses several cores, with simpler process management than Gunicorn offers.

A different programming model

If the codebase is mostly synchronous, such as blocking drivers or an ORM without async support, there are two options. You can keep FastAPI with plain def endpoints, or run a WSGI framework under Gunicorn's sync or threaded workers. Either way you avoid the event-loop stalls described below. You give up cheap concurrency for long-lived connections such as WebSockets.

How many workers should you run, and why is (2 x CPU) + 1 wrong for async?

The (2 x CPU) + 1 formula comes from Gunicorn's guidance for sync workers. A sync worker sits idle while it waits on the network or disk, so extra processes keep the cores busy during that wait. An async Uvicorn worker already overlaps I/O inside its event loop. Adding processes beyond the core count mostly adds memory, context switching and database connections, and it buys little extra throughput.

Start with roughly one worker per available core. Then run a load test and adjust based on three signals:

  • CPU saturation. If the cores sit well below full use while latency climbs, the bottleneck is somewhere else.
  • p99 latency. Tail latency shows event-loop contention before averages do.
  • Memory per worker. Every process loads its own copy of the app and its libraries.

Illustrative estimate

All inputs below are assumed:

  • 4 vCPU limit per pod
  • 6 replicas
  • SQLAlchemy pool size of 10 per worker
  • Database max_connections of 200

With 4 workers, the fleet can open 4 × 10 × 6 = 240 connections, which already exceeds the database limit. With the sync formula, 9 workers can open 540. You would need a smaller pool per worker or a connection pooler in front of the database.

Set the worker count explicitly

Inside containers, os.cpu_count() and nproc can report the host's cores instead of the cgroup CPU limit. On a large node, that can start dozens of workers in a pod limited to 2 CPUs. Set the worker count from configuration, such as an environment variable your deployment manifest controls. Do not derive it at runtime.

Measuring first costs a short load-test cycle. Guessing tends to cost more, through over-provisioned nodes and incident work chasing connection exhaustion or OOM kills.

import os

workers = int(os.environ["WEB_CONCURRENCY"])

worker_class = "uvicorn.workers.UvicornWorker"
bind = "0.0.0.0:8000"

pool_size = int(os.environ.get("DB_POOL_SIZE", "5"))
max_overflow = int(os.environ.get("DB_MAX_OVERFLOW", "0"))  # SQLAlchemy can exceed pool_size by this
replicas = int(os.environ.get("REPLICAS", "6"))
db_max_connections = int(os.environ.get("DB_MAX_CONNECTIONS", "200"))
reserved = int(os.environ.get("DB_RESERVED_CONNECTIONS", "20"))  # admin, migrations, other services

fleet_max = workers * (pool_size + max_overflow) * replicas
budget = db_max_connections - reserved

if fleet_max > budget:
    raise RuntimeError(
        f"DB connection budget exceeded: {workers} workers x "
        f"({pool_size}+{max_overflow}) x {replicas} replicas = {fleet_max} > {budget}. "
        "Lower the pool size or workers, or put a connection pooler in front of the database."
    )

A Gunicorn config file that takes the Uvicorn worker count from an explicit environment variable and refuses to start when workers × (pool size + overflow) × replicas would exceed the database connection limit.

Why does blocking code stall every request on a worker?

An async def endpoint runs directly on the worker's event loop. The loop is single-threaded and cooperative: it can only switch to another request when the running coroutine hits an await. A synchronous call such as a blocking database driver, requests.get(), time.sleep(), or a tight CPU loop never yields. For its whole duration, nothing else on that worker progresses. Other requests, health checks and keep-alive handling all wait.

Plain def endpoints behave differently. FastAPI dispatches them to a threadpool managed by AnyIO, so a blocking call there ties up one thread instead of the loop. The pool is finite, though. Under enough concurrent slow calls it saturates, and new requests queue for a free thread.

The symptom

Latency rises across all endpoints on one worker at once, including trivial ones that touch no I/O. Other workers look healthy. Per-route metrics hide this. Look at per-worker latency, or at event-loop lag if you instrument it.

The fixes

  • Use async drivers for databases and HTTP, and await them.
  • Wrap unavoidable sync calls in run_in_threadpool, or declare the endpoint as plain def.
  • Move CPU-heavy work to a task queue or a process pool. Threads won't help here because the GIL serializes the computation.

Gunicorn's timeout

A Uvicorn worker under Gunicorn sends its heartbeat from the event loop. If the loop stays blocked longer than --timeout, the arbiter treats the worker as hung and kills it, dropping every in-flight request on that worker. Raising the timeout stops the restarts but leaves the stall in place, so treat the restarts as the signal to find the blocking call.

import asyncio
import time
from concurrent.futures import ProcessPoolExecutor

import httpx
from fastapi import FastAPI
from fastapi.concurrency import run_in_threadpool

app = FastAPI()
process_pool = ProcessPoolExecutor(max_workers=2)  # separate processes sidestep the GIL

def legacy_lookup(user_id: int) -> dict:
    time.sleep(0.5)  # stands in for a blocking DB driver call
    return {"id": user_id}

def crunch(n: int) -> int:
    return sum(i * i for i in range(n))  # pure CPU, never yields

@app.get("/bad")
async def bad():
    # Runs on the event loop and never awaits: the whole worker stalls for 0.5 s
    return legacy_lookup(42)

@app.get("/http")
async def http_call():
    # Async client yields at each await, so other requests keep moving
    async with httpx.AsyncClient(timeout=5.0) as client:
        resp = await client.get("")
    return resp.json()

@app.get("/wrapped")
async def wrapped():
    # Unavoidable sync call pushed to the AnyIO threadpool
    return await run_in_threadpool(legacy_lookup, 42)

@app.get("/sync")
def sync_endpoint():
    # Plain def: FastAPI runs it in the threadpool; ties up one thread, not the loop
    return legacy_lookup(42)

@app.get("/cpu")
async def cpu():
    loop = asyncio.get_running_loop()
    return {"result": await loop.run_in_executor(process_pool, crunch, 10_000_000)}

One FastAPI app that contrasts a blocking call inside an async def endpoint with the fixes: an async HTTP client, run_in_threadpool, a plain def endpoint, and a process pool for CPU-bound work.

What breaks when each worker is a separate process?

Every worker is an independent Python process with its own copy of the application, so the FastAPI lifespan handler runs once per worker. With four workers, startup code runs four times and shutdown code runs four times. Anything kept in process memory is local to one worker.

State that silently splits

  • In-memory caches fill separately in each worker. Your hit rate is lower than it appears, and an invalidation only reaches the worker that received it.
  • Rate limiters that count requests in a dict let a client through roughly N times the intended limit, because the load balancer spreads that client's requests across workers.
  • WebSocket registries only contain the connections held by that worker. A broadcast from one worker skips clients connected to the others. Use a shared backend such as Redis or a message broker.
  • Schedulers started at startup run N copies, so each cron-style job fires N times. Run scheduled work in a separate process or protect it with a distributed lock.
  • Prometheus metrics come from whichever worker answers the scrape. Counters appear to jump around. The client library needs its multiprocess mode, which aggregates values through a shared directory.

Preloading and forking

Gunicorn's preload_app imports the app in the master process before forking, so workers start sharing memory pages through copy-on-write. The savings shrink over time. CPython writes reference counts into object headers whenever an object is touched, and each write copies the affected page into the worker.

Preloading also copies anything created before the fork. Event loops, database pools with open sockets, and HTTP client sessions do not work correctly after a fork. Children inherit the same file descriptors and loop state, which leads to corrupted connections or hangs. Create these resources inside lifespan so each worker builds its own.

import os
from contextlib import asynccontextmanager

import asyncpg
import httpx
from fastapi import FastAPI, Request

@asynccontextmanager
async def lifespan(app: FastAPI):
    # Runs once per worker, inside that worker's own event loop.
    pid = os.getpid()
    print(f"worker {pid}: startup")
    app.state.db = await asyncpg.create_pool(
        dsn="postgresql://app:example-password@db:5432/app",
        min_size=1,
        max_size=5,  # per worker: total connections = workers * max_size
    )
    app.state.http = httpx.AsyncClient(timeout=5.0)
    try:
        yield
    finally:
        # Also runs once per worker on graceful shutdown.
        await app.state.http.aclose()
        await app.state.db.close()
        print(f"worker {pid}: shutdown")

app = FastAPI(lifespan=lifespan)

@app.get("/whoami")
async def whoami(request: Request):
    # Repeated calls return different PIDs: each worker has its own state.
    async with request.app.state.db.acquire() as conn:
        now = await conn.fetchval("SELECT now()")
    return {"pid": os.getpid(), "db_time": str(now)}

Database pools and HTTP clients are created in the FastAPI lifespan handler so each worker builds its own after the fork. The startup and shutdown messages print once per worker, and /whoami shows that requests land on different processes.

How do you configure proxies, keep-alive and graceful shutdown?

The second piece of per-worker setup is making each worker see the client the way the edge does.

Proxy headers

Behind a load balancer, every request arrives from the proxy's address over plain HTTP. Run Uvicorn with --proxy-headers and set --forwarded-allow-ips to your proxy's addresses so that request.client and request.url.scheme reflect X-Forwarded-For and X-Forwarded-Proto. Under Gunicorn, set forwarded_allow_ips in the Gunicorn config. Avoid * unless the server is reachable only through the proxy. Otherwise any client can spoof its IP and scheme, which breaks rate limiting, audit logs and HTTPS redirects.

Keep-alive and health checks

Set the proxy's upstream idle timeout shorter than the server's keep-alive (--timeout-keep-alive, or keepalive in Gunicorn). If the server closes an idle connection first, the proxy can send a request on a socket that is already closed and return intermittent 502s.

Point health checks at an endpoint that touches no database. A slow dependency should not cause the load balancer to mark healthy workers as down.

Graceful shutdown

On SIGTERM, the server stops accepting connections and drains in-flight requests for up to --timeout-graceful-shutdown (or Gunicorn's graceful_timeout). That drain must fit inside the orchestrator's termination grace period, with room left over. The load balancer may keep routing traffic until deregistration completes, so a short pre-stop delay helps.

Worker recycling

--max-requests with --max-requests-jitter restarts each Gunicorn worker after a randomized number of requests. Without jitter, workers that started together also restart together, and capacity drops all at once. Uvicorn's --limit-max-requests gives you the same cap. Treat recycling as containment, not a fix: it hides memory leaks you should still profile.

How can it save engineering time?

Picking the topology on purpose saves time mainly because it removes recurring work and whole classes of incidents. Raw speed is a smaller factor.

  • One supervision layer means one set of knobs. When only the orchestrator restarts and health-checks processes, a restart policy, timeout or probe change happens in one place. Stacked supervisors force engineers to work out which layer killed a process before they can start fixing anything.
  • Fewer moving parts in the single-process topology. One Uvicorn process per container needs no Gunicorn dependency, no worker class import path to track across upgrades, and no gunicorn.conf.py to keep in sync with the manifest. Scaling becomes a change to the replica count.
  • Startup guards catch misconfiguration before an incident. A config check like the connection-budget guard above turns a production outage into a failed deploy with a clear error message. That kind of failure is cheaper to diagnose and roll back than connection exhaustion under load.
  • Explicit worker counts make behavior reproducible. If workers come from configuration and not from os.cpu_count(), the same image behaves the same on every node. This rules out a class of "works in staging, OOMs in production" investigations.
  • Known failure signatures shorten debugging. Once the team knows that latency rising on one worker means a blocking call on the event loop, and that repeated Gunicorn timeout kills mean the same thing, they can go straight to the cause. A double-firing job points to per-worker schedulers, and intermittent 502s point to keep-alive ordering.
  • Shared state is designed once. Moving caches, rate limits, WebSocket fan-out and schedules to shared backends early avoids rewriting them later. A late rewrite usually follows a bug that only showed up after someone raised the worker count.

Illustrative estimate

All inputs are assumed. Suppose a team spends half a day each time it investigates a stacked-supervisor timeout conflict or a connection-exhaustion incident, and this happens once a quarter per service across 8 services. That adds up to about 16 engineer-days a year. Collapsing to one supervision layer and adding a startup budget guard is a one-time change per service. If it prevents most of those investigations, the time saved is close to that recurring cost. Use your own incident history in place of these assumed inputs.

What does a baseline production config look like for each topology?

Three baseline commands

  • Uvicorn only, for container platforms that scale by replica: uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips <proxy-ip>. The orchestrator restarts the process and adds replicas, so the process itself stays simple.
  • Uvicorn with workers, for a VM where one process should use several cores: add --workers 4 --timeout-keep-alive 5 --timeout-graceful-shutdown 30. Uvicorn's supervisor restarts dead workers, but its process management is more basic than Gunicorn's.
  • Gunicorn with Uvicorn workers, when you need mature process management such as signal-driven reloads and worker timeouts: gunicorn app.main:app -k uvicorn.workers.UvicornWorker -w 4 -b 0.0.0.0:8000 --timeout 30 --graceful-timeout 30 --keep-alive 5. Check which package provides the worker class for your Uvicorn release.

Use one supervision layer. If you stack Gunicorn under systemd under an orchestrator, you have three sets of restart policies and timeouts. They can contradict each other, and each needs updating whenever another changes.

Pre-rollout checklist

  • Set the worker count explicitly so it doesn't follow whatever machine the code lands on.
  • Bind to 0.0.0.0 inside containers. Bind to localhost or a Unix socket behind a local proxy.
  • Make the shutdown timeouts shorter than the platform's kill grace period.
  • Trust forwarded headers only from your proxy's addresses.
  • Use structured logs. Decide whether the proxy or the app writes access logs, not both, and disable the other with --no-access-log.
  • Install uvicorn[standard] to get uvloop and httptools.
  • Load-test with your own request mix, because benchmarks from other workloads don't predict your latency.

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 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.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

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.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • 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.