Skip to content

# Installation

Note

Gunicorn requires Python 3.12 or newer.

## Quick Install

pip pipx Docker System Packages

    pip install gunicorn

    pipx install gunicorn

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

See the Docker guide for production configurations.

Debian/Ubuntu:

    sudo apt-get update
    sudo apt-get install gunicorn

Fedora:

    sudo dnf install python3-gunicorn

Arch Linux:

    sudo pacman -S gunicorn

Warning

System packages may lag behind the latest release. For production, prefer pip installation in a virtual environment.

## Virtual Environment (Recommended)

Always install Gunicorn inside a virtual environment to isolate dependencies:

    # Create virtual environment
    python -m venv venv

    # Activate it
    source venv/bin/activate  # Linux/macOS
    # or: venv\Scripts\activate  # Windows

    # Install gunicorn
    pip install gunicorn

## From Source

Install the latest development version from GitHub:

    pip install git+https://github.com/benoitc/gunicorn.git

Upgrade to the latest commit:

    pip install -U git+https://github.com/benoitc/gunicorn.git

## Extra Packages

Gunicorn provides optional extras for additional worker types and features. Install them with pip's bracket syntax:

    pip install gunicorn[gevent,setproctitle]

### Worker Types

Extra | Description
--- | ---
`gunicorn[gevent]` | Gevent-based greenlet workers
`gunicorn[gthread]` | Threaded workers
`gunicorn[tornado]` | Tornado-based workers (not recommended)
`gunicorn[eventlet]` | Deprecated - will be removed in 26.0

See the design docs for guidance on choosing worker types.

### Utilities

Extra | Description
--- | ---
`gunicorn[setproctitle]` | Set process name in `ps`/`top` output

Tip

If running multiple Gunicorn instances, use `setproctitle` with the `proc_name` setting to distinguish them.

## Async Workers

For applications using async I/O patterns, install the appropriate greenlet library:

Gevent ASGI (asyncio)

    pip install gunicorn[gevent]

Run with:

    gunicorn app:app --worker-class gevent

No extra installation required:

    gunicorn app:app --worker-class asgi

For better performance, install uvloop:

    pip install uvloop
    gunicorn app:app --worker-class asgi --asgi-loop uvloop

Note

Greenlet-based workers require the Python development headers. On Ubuntu: `sudo apt-get install python3-dev`

## Verify Installation

Check the installed version:

    gunicorn --version

Test with a simple application:

    echo 'def app(e, s): s("200 OK", []); return [b"OK"]' > test_app.py
    gunicorn test_app:app
    # Visit http://127.0.0.1:8000

## Next Steps

- Quickstart - Get running in 5 minutes
- Run - CLI usage and framework integration
- Configure - Configuration options