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:VARIABLE_NAME

Example:
gunicorn --bind 0.0.0.0:8000 --workers 3 myproject.wsgi:application
gunicorn --chdir /path/to/app myapp:app

--bind ADDRESS, -b ADDRESS
    The socket to bind. Can be IP:PORT, hostname:PORT, or a Unix socket path (e.g., '0.0.0.0:8000', '/tmp/gunicorn.sock').

--workers INT, -w INT
    The number of worker processes to spawn. A common recommendation is (2 x $NUM_CORES) + 1.

--worker-class CLASS, -k CLASS
    The type of worker to use (e.g., 'sync', 'gevent', 'eventlet'). Defaults to 'sync'.

--threads INT
    The number of threads per worker for multi-threaded worker classes. Requires a compatible worker class.

--timeout INT
    Workers silent for more than this many seconds are killed and restarted. Defaults to 30 seconds.

--log-level LEVEL
    The granularity of log output. Options include 'debug', 'info', 'warning', 'error', 'critical'.

--access-logfile FILE
    The access log file to write to. Use '-' for stdout.

--error-logfile FILE
    The error log file to write to. Use '-' for stderr.

--daemon
    Daemonize the Gunicorn process, running it in the background.

--pid FILE
    A file to write the master process PID to.

--user USER
    Switch worker processes to run as this user.

--group GROUP
    Switch worker processes to run as this group.

-c CONFIG, --config CONFIG
    The Gunicorn configuration file to use (a Python file defining settings).

--chdir PATH
    Change to the specified directory before loading the application.

--env KEY=VALUE
    Set an environment variable for worker processes.

Gunicorn (Green Unicorn) is a pre-fork worker model HTTP server for WSGI applications written in Python. It acts as a robust and high-performance intermediary, forwarding requests from a front-end web server (like Nginx or Apache) to your Python web application (e.g., Django, Flask). Its simplicity, efficiency, and broad compatibility make it a popular choice for deploying Python web projects.

Gunicorn manages multiple worker processes, each handling incoming requests, ensuring concurrency and responsiveness. It's designed for stability and resource efficiency, making it suitable for production environments. While Gunicorn serves your application code, it's generally recommended to place it behind a reverse proxy for handling static files, SSL termination, load balancing, and other advanced web server features, optimizing overall performance and security.

Gunicorn is designed to serve as an application server and should typically be run behind a reverse proxy (like Nginx or Apache). It is not optimized for serving static files, SSL termination, or advanced load balancing, which are best handled by a dedicated web server. Proper tuning of the number of worker processes is crucial for optimal performance and resource usage; too few can bottleneck, too many can exhaust resources.

Gunicorn supports various worker classes to handle different concurrency models.
'sync' (default): Synchronous workers, one request at a time. Simple and robust for CPU-bound tasks.
'gevent' / 'eventlet': Asynchronous workers using greenlets, suitable for I/O-bound applications requiring high concurrency.
'tornado' / 'meinheld': Specialized asynchronous workers leveraging their respective frameworks' I/O loops.

For production deployments, Gunicorn is almost always used in conjunction with a reverse proxy server such as Nginx or Apache. The reverse proxy handles public-facing responsibilities like SSL/TLS termination, serving static assets, caching, and load balancing, while Gunicorn focuses solely on executing the Python application code, communicating via HTTP or Unix sockets.

Gunicorn was initially developed by Benoît Chesneau and first released in 2010. Its design was inspired by Ruby's Unicorn HTTP server, focusing on a pre-fork worker model for handling concurrent requests. From its inception, Gunicorn aimed to provide a simple, high-performance, and robust WSGI server for Python web applications, quickly gaining popularity as a reliable choice for deploying frameworks like Django and Flask due to its stability and ease of integration.

nginx(8), apache2(8), systemd(1), supervisor(1), uwsgi(1)