Python Web Servers Cheat Sheet

1Install & runASGI

pip install "uvicorn[standard]"★
[standard] adds the fast extras: uvloop, httptools, websockets, and watchfiles (for reload). Plain uvicorn is pure-Python.
uvicorn main:app★
Run the ASGI callable app in main.py. Serves on 127.0.0.1:8000 by default. Works with FastAPI/Starlette/Django-ASGI.
uvicorn main:app --host 0.0.0.0 --port 8000★
0.0.0.0 to accept external connections. This is the minimal production-ish invocation.
uvicorn main:app --reload # dev auto-reload★
--reload restarts on file changes — dev only (never in production).

2CLI optionsthe useful flags

uvicorn main:app --workers 4★
Run 4 worker processes — Uvicorn now manages its own multiprocessing (you no longer need Gunicorn just for this). Mutually exclusive with --reload.
uvicorn main:app --log-level warning --no-access-log
Control logging. --log-config file.json/.yaml for full control.
uvicorn main:app --proxy-headers --forwarded-allow-ips '*'★
Trust X-Forwarded-For/Proto when behind nginx/a load balancer so the app sees the real client IP/scheme.
uvicorn main:app --env-file .env --timeout-keep-alive 5
Load env vars; tune keep-alive. --loop uvloop, --http httptools, --lifespan on also available.

3Programmatic & reloadrun from code

import uvicorn if __name__ == "__main__": uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)★
Start Uvicorn from Python. ⚠️ Pass the app as an import string ("main:app"), not the object, when using reload=True/workers=.
async def app(scope, receive, send): ... # a raw ASGI app
Any ASGI callable works; usually it's a framework instance (app = FastAPI()).
# uvicorn.run(app_object, reload=True) -> reload won't workgotcha
Reload & multiple workers require the import-string form so child processes can re-import the app.

4Install & runWSGI · UNIX

pip install gunicorn★
⚠️ UNIX/macOS only — Gunicorn does not run on Windows (use Uvicorn, Hypercorn, or Waitress there).
gunicorn main:app★
Serve the WSGI callable app from main.py (Flask/Django). Django: gunicorn myproject.wsgi:application.
gunicorn main:app -b 0.0.0.0:8000 -w 4★
-b bind address, -w worker count. This is the everyday production command.
gunicorn main:app --reload # dev only
Auto-reload on code changes for development.

5Workers & worker classesconcurrency model

-w $((2 * $(nproc) + 1)) # rule of thumb: 2*CPU + 1★
Start with 2×cores+1 workers for CPU-bound sync apps, then measure.
gunicorn main:app -k gthread --threads 4★
Worker classes: sync (default, one request at a time), gthread (threads per worker — good for I/O), gevent/eventlet (async via greenlets).
--max-requests 1000 --max-requests-jitter 100★
Recycle a worker after N requests (± jitter) to bound memory leaks — a common production safeguard.
--preload # load app before forking workers
Saves memory (copy-on-write) & catches import errors early, but disables --reload and per-worker fork setup.

6Config filegunicorn.conf.py

# gunicorn.conf.py (auto-loaded from CWD) bind = "0.0.0.0:8000" workers = 4 worker_class = "uvicorn_worker.UvicornWorker" timeout = 30★
A Python config file is the clean way to configure Gunicorn — every CLI flag has an equivalent variable. Auto-loaded if named gunicorn.conf.py.
gunicorn main:app -c gunicorn.conf.py
Or point at any path with -c.
accesslog = "-"; errorlog = "-"; loglevel = "info" preload_app = True; keepalive = 5
"-" logs to stdout/stderr (ideal for containers). Set proxy_allow_ips, forwarded_allow_ips behind a proxy.
def post_fork(server, worker): ... # lifecycle hooks
Hooks (on_starting, post_fork, worker_int, on_exit) run Python at each lifecycle stage.

7Gunicorn + Uvicorn workersFastAPI in prod

pip install uvicorn-worker★changed
⚠️ The Uvicorn worker class moved to its own package. Install uvicorn-worker separately.
gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker -b 0.0.0.0:8000★
The canonical ASGI production command: Gunicorn manages 4 Uvicorn workers. Gunicorn handles supervision/restarts; each worker runs the async event loop.
# OLD: -k uvicorn.workers.UvicornWorker -> deprecated/removedmigration
The in-tree uvicorn.workers.UvicornWorker was removed from Uvicorn. Switch to uvicorn_worker.UvicornWorker from the uvicorn-worker package.
worker_class = "uvicorn_worker.UvicornWorkerH11" # pure-python h11 variant
Variants exist (e.g. an h11-based worker) when you can't build httptools.

8Which multi-worker?gunicorn vs uvicorn --workers

# uvicorn --workers N (simple, one tool)★
Uvicorn's own multiprocessing is fine for many deployments — fewer moving parts. Good default now that it exists.
# gunicorn -k UvicornWorker (richer process management)
Choose Gunicorn when you want its mature supervision: --max-requests recycling, graceful HUP reloads, TTIN/TTOU worker scaling, and battle-tested signal handling.
# containers/k8s: often 1 worker/process, scale via replicas
Under an orchestrator, many teams run a single process per container and scale horizontally — then the choice matters less.

9Timeouts, reload & signalsoperate it

gunicorn ... --timeout 30 --graceful-timeout 30 --keep-alive 5★
--timeout: a worker silent this long is killed & restarted (raise it for slow requests, or use async workers). --graceful-timeout: how long to finish in-flight requests on reload.
kill -HUP $(cat gunicorn.pid) # graceful config/code reload★
HUP reloads workers with (near) zero downtime. --pid gunicorn.pid to write the master PID.
kill -TTIN / -TTOU pid # add / remove one worker kill -USR2 pid # hot-upgrade the binary
Gunicorn's signal toolkit: scale workers live, and do zero-downtime binary upgrades with USR2 + WINCH.
# WORKER TIMEOUT killing a slow sync request?gotcha
A long request on a sync worker blocks it and trips --timeout. Use gthread/async workers, offload to a task queue, or raise the timeout.

10Binding, sockets & proxiesthe network edge

gunicorn ... -b unix:/run/app.sock # uvicorn: --uds /run/app.sock★
Bind a Unix domain socket to talk to nginx on the same host — faster & more secure than a TCP port.
# behind a proxy: trust forwarded headers gunicorn ... --forwarded-allow-ips "*" uvicorn ... --proxy-headers --forwarded-allow-ips "*"★
So the app sees the real client IP/scheme from X-Forwarded-*. Restrict the allowed IPs in production.
uvicorn ... --ssl-keyfile key.pem --ssl-certfile cert.pem
TLS termination is possible in the app server, but usually you let nginx/the load balancer terminate TLS.

11systemd, Docker & nginxrun it for real

# /etc/systemd/system/app.service [Service] ExecStart=/venv/bin/gunicorn main:app -c gunicorn.conf.py Restart=always★
systemd supervises the master process & restarts on failure — the standard VM/bare-metal deploy.
# Dockerfile CMD ["gunicorn", "main:app", "-k", "uvicorn_worker.UvicornWorker", "-b", "0.0.0.0:8000"]★
Bind 0.0.0.0, log to stdout (accesslog="-"), and let the orchestrator restart the container. Don't use --reload.
# nginx: proxy_pass to the app socket/port; it serves static + TLS
Put nginx (or a cloud LB) in front for TLS, static files, buffering, and rate limiting; proxy dynamic requests to Gunicorn/Uvicorn.

12Alternatives & choosingthe landscape

# Hypercorn — ASGI, HTTP/2 + HTTP/3, asyncio or trio
Hypercorn: the ASGI alternative to Uvicorn when you need HTTP/2/3 or trio. hypercorn main:app --workers 4.
# Granian — Rust-based, serves ASGI + WSGI + RSGI, very fast
Granian: a fast Rust server handling ASGI, WSGI, and its own RSGI — a rising single-tool option.
# Waitress — pure-Python WSGI, works on Windows
Waitress is the go-to WSGI server on Windows (where Gunicorn can't run). Daphne for Django Channels.
# pick: async app -> Uvicorn/Hypercorn/Granian; sync -> Gunicorn/Waitress★
Match the server to your app's interface (ASGI vs WSGI). For ASGI in production, Gunicorn+UvicornWorker or plain uvicorn --workers are both solid.

Python Web Servers cheat sheet

Outline

Uvicorn (ASGI)

Gunicorn (WSGI)

The combo

Tuning & lifecycle

Deploy & alternatives

Uvicorn (ASGI)

Gunicorn (WSGI)

The Production Combo

Tuning & Lifecycle

Deploy & Alternatives

Worth memorizing