Running Gunicorn

You can run Gunicorn directly from the command line or integrate it with popular frameworks like Django, Pyramid, or TurboGears. For deployment patterns see the deployment guide.

Commands

After installation you have access to the gunicorn executable.

gunicorn

Basic usage:

gunicorn [OPTIONS] [WSGI_APP]

WSGI_APP follows the pattern MODULE_NAME:VARIABLE_NAME. The module can be a full dotted path. The variable refers to a WSGI callable defined in that module.

Changed in 20.1.0

WSGI_APP can be omitted when defined in a configuration file.

Example test application:

def app(environ, start_response):
    """Simplest possible application object"""
    data = b"Hello, World!\n"
    status = "200 OK"
    response_headers = [
        ("Content-type", "text/plain"),
        ("Content-Length", str(len(data.md)))
    ]
    start_response(status, response_headers)
    return iter([data])

Run it with:

gunicorn --workers=2 test:app

You can also expose a factory function that returns the application:

def create_app():
    app = FrameworkApp()
    ...
    return app

gunicorn --workers=2 'test:create_app()'

Passing positional and keyword arguments is supported but prefer configuration files or environment variables for anything beyond quick tests.

Commonly used arguments

• -c CONFIG, --config CONFIG — configuration file (PATH, file:PATH, or python:MODULE_NAME).
• -b BIND, --bind BIND — socket to bind (host, host:port, fd://FD, or unix:PATH).
• -w WORKERS, --workers WORKERS — number of worker processes, typically two to four per CPU core. See the FAQ for tuning tips.
• -k WORKERCLASS, --worker-class WORKERCLASS — worker type (sync, eventlet, gevent, tornado, gthread). Read the settings entry before switching classes.
• -n APP_NAME, --name APP_NAME — set the process name (requires setproctitle).

You can pass any setting via the environment variable GUNICORN_CMD_ARGS. See the configuration guide and settings reference for details.

Integration

Gunicorn integrates cleanly with Django and Paste Deploy applications.

Django

Gunicorn looks for a WSGI callable named application. A typical invocation is:

gunicorn myproject.wsgi

Note

Ensure your project is on PYTHONPATH. The easiest way is to run this command from the directory containing manage.py.

Set environment variables with --env and add your project to PYTHONPATH if needed:

gunicorn --env DJANGO_SETTINGS_MODULE=myproject.settings myproject.wsgi

See raw_env and pythonpath for more options.

Paste Deployment

Frameworks such as Pyramid and TurboGears often rely on Paste Deployment configuration. You can use Gunicorn in two ways.

As a Paste server runner

Let your framework command (for example pserve or gearbox) load Gunicorn by configuring it as the server:

[server:main]
use = egg:gunicorn#main
host = 127.0.0.1
port = 8080
workers = 3

This approach is quick to set up but Gunicorn cannot control how the application loads. Options like reload will be ignored and hot upgrades are unavailable. Features such as daemon mode may conflict with what your framework already provides. Prefer running those features through the framework (for example pserve --reload). Advanced configuration is still possible by pointing the config key at a Gunicorn configuration file.

Using Gunicorn's Paste support

Use the paste option to load a Paste configuration directly with the Gunicorn CLI. This unlocks Gunicorn's reloader and hot code upgrades, while still letting Paste define the application object.

gunicorn --paste development.ini -b :8080 --chdir /path/to/project

Select a different application section by appending the name:

gunicorn --paste development.ini#admin -b :8080 --chdir /path/to/project

In both modes Gunicorn will honor any Paste loggers configuration unless you override it with Gunicorn-specific logging settings.