Gunicorn Documentation

Gunicorn resolves configuration settings from five sources. If multiple sources define the same setting, the source with the higher priority wins. The priority order (from lowest to highest) is:

1. Environment variables (only for settings that support them).
2. Framework-specific configuration (currently only supported for Paste Deploy).
3. Python configuration file (defaults to gunicorn.conf.py in the working directory).
4. GUNICORN_CMD_ARGS environment variable.
5. Command-line arguments.

Note: If a configuration file is specified via both GUNICORN_CMD_ARGS and the CLI, only the file specified on the command line is used.

Gunicorn is compatible with various WSGI and ASGI frameworks and offers different worker models depending on your workload:

Supported Frameworks

• WSGI: Django, Flask, Pyramid, Falcon, Bottle
• ASGI: FastAPI, Starlette, Quart

Worker Types

• Sync: The default model. One request per worker. Simple and predictable.
• Async (Gevent/Eventlet): Designed for I/O-bound workloads, handling thousands of concurrent connections.
• Threads: Multiple threads per worker to balance concurrency and simplicity.
• ASGI: Native asyncio support for async frameworks like FastAPI and Starlette.

Gunicorn ('Green Unicorn') is a Python WSGI HTTP Server for UNIX using a pre-fork worker model. Key features include:

• WSGI Support: Compatible with Django, Flask, Pyramid, and other WSGI frameworks.
• ASGI Support: Compatible with FastAPI, Starlette, and Quart.
• HTTP/2 Support (beta): Includes multiplexed streams.
• Dirty Arbiters (beta): Designed for heavy workloads like ML models or long-running tasks.
• Worker Types: Supports sync, gthread, gevent, and asgi worker classes.
• Nginx Integration: Supports the uWSGI binary protocol.
• Compatibility: Works with Python 3.9+.

You can provide settings to Gunicorn using the GUNICORN_CMD_ARGS environment variable. This is useful for passing multiple command-line arguments at once.

Example:

$ GUNICORN_CMD_ARGS="--bind=127.0.0.1 --workers=3" gunicorn app:app

For improved performance, you can use the uWSGI protocol with Nginx's uwsgi_pass.

Warning: WebSocket connections are not supported when using the uWSGI protocol. Use an HTTP proxy for WebSocket endpoints.

gunicorn myapp:app --worker-class asgi --protocol uwsgi --bind 127.0.0.1:8000

upstream gunicorn {
    server 127.0.0.1:8000;
}

server {
    listen 80;
    server_name example.com;

    location / {
        uwsgi_pass gunicorn;
        include uwsgi_params;
    }
}

To run Gunicorn quickly, mount your application directory and run the container. Replace app:app with your application module and callable.

docker run -p 8000:8000 -v $(pwd):/app ghcr.io/benoitc/gunicorn app:app

To use Gunicorn, install it via pip and then run it by specifying your application import path in the format module:callable. By default, it listens on http://127.0.0.1:8000.

pip install gunicorn
gunicorn myapp:app

The gunicornc CLI is used to interact with the Gunicorn control socket. You can use it in Interactive Mode (by running gunicornc without arguments) or via Single Commands for scripting.

Common CLI Flags:

• -s <path>: Connect to a custom socket path.
• -c <command>: Run a single command and exit.
• -j: Output the result as JSON (ideal for scripting).

Example usage:

# Connect to default socket
gunicornc

# Connect to custom socket
gunicornc -s /tmp/myapp.ctl

# Run a single command
gunicornc -c "show workers"

# Output as JSON for scripting
gunicornc -c "show stats" -j

For applications using async I/O patterns, you can use specific worker classes.

Gevent

Requires the gevent extra and Python development headers (e.g., sudo apt-get install python3-dev on Ubuntu).

ASGI (asyncio)

No extra installation required. For improved performance, it is recommended to install and use uvloop.

# Gevent
pip install gunicorn[gevent]
gunicorn app:app --worker-class gevent

# ASGI (asyncio)
gunicorn app:app --worker-class asgi

# ASGI with uvloop (Recommended for performance)
pip install uvloop
gunicorn app:app --worker-class asgi --asgi-loop uvloop

Gunicorn provides an official Docker image on the GitHub Container Registry. You can pull the latest image or specific versions using the following tags:

• ghcr.io/benoitc/gunicorn:latest - Latest release
• ghcr.io/benoitc/gunicorn:24.1.0 - Specific version
• ghcr.io/benoitc/gunicorn:24.1 - Minor version
• ghcr.io/benoitc/gunicorn:24 - Major version

docker pull ghcr.io/benoitc/gunicorn:latest