Gunicorn guide

What Gunicorn does in production

Gunicorn runs Python web applications that speak the WSGI protocol. It does not serve static files or terminate TLS in most setups — nginx or another reverse proxy handles that and forwards requests to Gunicorn over HTTP or a Unix socket. A master process manages worker processes that handle requests concurrently.

How a request is handled

In a typical production stack:

1. Reverse proxy — nginx/Apache receives the client connection on port 80/443
2. Forward — proxy passes the request to Gunicorn via proxy_pass or a Unix socket
3. Master accepts — Gunicorn master receives the connection and hands it to a free worker
4. WSGI call — the worker invokes your application callable (module:app)
5. Response — the app returns an iterable response; Gunicorn streams it back to the proxy

The application entry point is specified as myproject.wsgi:application (Django) or app:app (Flask) — module path plus callable name.

Workers and concurrency

• --workers — number of worker processes (rule of thumb: 2 × CPU + 1 for sync workers)
• --worker-class — sync (default), gevent, gthread for async/threaded workloads
• --threads — per-worker threads when using gthread
• --timeout — kill workers silent longer than this (default 30s)
• --max-requests — restart workers after N requests (memory leak mitigation)

Binding and deployment

Gunicorn binds to an address workers listen on:

• TCP — --bind 127.0.0.1:8000 (localhost only; proxy connects here; more flexible for containers)
• Unix socket — --bind unix:/run/gunicorn.sock (lower overhead, faster but only works locally; proxy uses proxy_pass http://unix:/run/gunicorn.sock)

Production deployments usually run Gunicorn under systemd with a unit file, or historically under supervisord. Config can live in gunicorn.conf.py (Python file; supports logic, recommended for complex configs) or command-line flags (simple/quick; good for testing).

Key settings to know

• --chdir — working directory before loading the app
• --user / --group — drop privileges after binding
• --access-logfile / --error-logfile — log destinations (- for stdout)
• --reload — dev only; auto-restart on code changes
• --graceful-timeout — time to finish in-flight requests on reload/shutdown

Learning resources

• Gunicorn documentation — docs.gunicorn.org (official docs)
• Settings — docs.gunicorn.org/settings (all configuration options)
• Deploying Gunicorn — docs.gunicorn.org/deploy (production deployment guide)
• Django deployment — docs.djangoproject.com — Gunicorn (Django + Gunicorn setup)