Skip to content

# 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`, `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.