Skip to content

Installation

Note

Gunicorn requires Python 3.12 or newer.

Quick Install

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.

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[eventlet] Eventlet-based greenlet workers
gunicorn[gevent] Gevent-based greenlet workers
gunicorn[gthread] Threaded workers
gunicorn[tornado] Tornado-based workers (not recommended)

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:

pip install gunicorn[gevent]

Run with: 

gunicorn app:app --worker-class gevent


pip install gunicorn[eventlet]

Run with: 

gunicorn app:app --worker-class eventlet

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