gunicorn

Run Python web app

$ gunicorn [import.path:app_object]

$ gunicorn [[-b|--bind]] [localhost]:[8080] [import.path:app_object]

$ gunicorn --reload [import.path:app_object]

$ gunicorn [[-w|--workers]] [4] [import.path:app_object]

$ gunicorn --threads [4] [import.path:app_object]

$ gunicorn --certfile [cert.pem] --keyfile [key.pem] [import.path:app_object]

gunicorn [OPTIONS] [APP_MODULE]

-w INT, --workers INT
    Number of worker processes (default: 1). Use (2 x $num_cores) + 1 formula.

--bind ADDRESS
    Socket to bind (e.g., 127.0.0.1:8000, unix:/tmp/gunicorn.sock).

-k STRING, --worker-class STRING
    Worker class (sync, eventlet, gevent, tornado, gthread, async).

--worker-connections INT
    Max client connections per worker (async workers only).

--max-requests INT
    Max requests per worker before restart (prevents leaks).

--max-requests-jitter INT
    Random variance for max-requests (default: 0).

-t INT, --timeout INT
    Worker timeout in seconds (default: 30).

--graceful-timeout INT
    Graceful worker restart timeout (default: 30s).

--keep-alive INT
    Keep-alive timeout (0 disables, default: 2s).

-c FILE, --config FILE
    Config file path (INI or Python format).

-D, --daemon
    Daemonize into background.

-p FILE, --pid FILE
    PID file location.

--preload-app
    Load app before forking workers.

--reload
    Reload on code changes (dev only).

--log-level LEVEL
    Log level (debug, info, warning, error, critical).

--access-logfile FILE
    Access log file path.

--error-logfile FILE
    Error log file path.

Gunicorn, short for Green Unicorn, is a high-performance Python WSGI HTTP server designed for UNIX-like systems. It implements a pre-fork worker model inspired by Ruby's Unicorn project, making it ideal for deploying Python web applications in production environments.

Gunicorn excels in handling concurrent requests efficiently by spawning multiple worker processes, each capable of serving multiple clients simultaneously. It supports various worker types, including sync, eventlet, gevent, tornado, and async for high-concurrency scenarios. Key features include automatic worker restarts to prevent memory leaks via max_requests, graceful restarts for zero-downtime deployments, Unix socket support for integration with reverse proxies like Nginx, and extensive logging options.

Commonly used with frameworks like Django, Flask, and Pyramid, Gunicorn is not suited for Windows and requires a UNIX environment. It binds to specified addresses, supports SSL/TLS, and allows configuration via command-line flags, INI-style files, or Python modules. For optimal performance, it's often paired with Nginx as a reverse proxy to handle static files and load balancing.

Its lightweight design, combined with robust error handling and monitoring capabilities, makes it a staple in Python web deployment stacks, serving applications from small APIs to large-scale services.

Not supported on Windows; use with reverse proxy like Nginx for production; --reload unsafe for multi-worker setups; async workers need monkey-patching libraries.

Specifies app as <module>:<object> (e.g., myapp:app or myproject.wsgi:application). Paste callable must be WSGI-compliant.

Optimal workers: 2-4 per CPU core. Use gevent/eventlet for IO-bound apps; sync for CPU-bound.

Supports UNIX signals: TERM/INT (quick shutdown), QUIT (graceful), HUP (reload), TTIN/TTOU (worker adjust).

Created by Benoit Chesneau in 2010 as a Python port of Ruby's Unicorn. First release 0.1.0; current stable around 21.x (2023). Widely adopted in Python ecosystem for its reliability and performance.

nginx(8), uwsgi(1), supervisord(1)