Gunicorn & Uvicorn

Gunicorn manages worker processes for WSGI and ASGI apps; Uvicorn implements the ASGI server. Production FastAPI on 0.115+ commonly uses Gunicorn with UvicornWorker for multi-process concurrency plus async I/O.

Recipe

gunicorn app.main:app \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  -b 0.0.0.0:8000 \
  --timeout 60 \
  --graceful-timeout 30 \
  --access-logfile -

When to reach for this:

• Production FastAPI/Starlette deployments
• Flask/Django WSGI with sync workers (-k sync default)
• Container single-process model with internal worker pool
• Graceful deploys needing SIGTERM handling

Working Example

Tuned Gunicorn config file for FastAPI with logging and worker count from env.

# gunicorn.conf.py
import multiprocessing
import os
 
bind = f"0.0.0.0:{os.environ.get('PORT', '8000')}"
worker_class = "uvicorn.workers.UvicornWorker"
workers = int(os.environ.get("WEB_CONCURRENCY", multiprocessing.cpu_count()))
timeout = 60
graceful_timeout = 30
keepalive = 5
accesslog = "-"
errorlog = "-"
loglevel = os.environ.get("LOG_LEVEL", "info")

gunicorn -c gunicorn.conf.py app.main:app

What this demonstrates:

• WEB_CONCURRENCY pattern matches Heroku/Render conventions
• UvicornWorker runs ASGI per worker process
• Access/error logs to stdout for container log collectors

Deep Dive

Worker Models

Tuning Starting Points

• Workers: 2-4 x CPU cores for sync CPU-bound; fewer for memory-heavy ML
• Timeout: above p99 request time; avoid killing slow legitimate requests
• Keepalive: match reverse proxy keepalive settings

Python Notes

# Dev only - single worker reload
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

Gotchas

• Too many workers on ML app - OOM kills container. Fix: reduce workers or externalize inference.
• Sync workers for purely async I/O app - underutilizes concurrency. Fix: UvicornWorker or pure uvicorn with async.
• Timeout shorter than DB query - 502 during reports. Fix: raise timeout or move long jobs to queue.
• No graceful timeout on deploy - in-flight requests aborted. Fix: --graceful-timeout + preStop hook delay in K8s.
• Running uvicorn --reload in prod - insecure and unstable. Fix: gunicorn config without reload.

Alternatives

FAQs

Related

• Deployment Basics - WSGI/ASGI intro
• Dockerizing Python - CMD uses Gunicorn
• Zero-Downtime Deploys - graceful shutdown
• Health & Readiness - probes
• Performance Monitoring (APM) - latency tuning

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.