mirror of https://github.com/frappe/gunicorn.git synced 2026-07-01 18:21:30 +08:00

Benoit Chesneau 315e7bde80 fix(http2): ALPN negotiation for gevent/eventlet workers

- Add explicit do_handshake() in base_async.py before ALPN check
  when do_handshake_on_connect is False
- Mark eventlet worker as deprecated (removal in 26.0)
- Add HTTP/2 gevent example with Docker and tests
- Update documentation to reflect eventlet deprecation
- Remove eventlet websocket example (gevent version exists)

The ALPN fix ensures HTTP/2 works correctly with gevent and eventlet
workers when do_handshake_on_connect config is False (the default).
Without explicit handshake, selected_alpn_protocol() returns None.

2026-01-28 13:42:48 +01:00

3.3 KiB

Raw Blame History

Installation

!!! note Gunicorn requires Python 3.12 or newer.

Quick Install

=== "pip"

```bash
pip install gunicorn
```

=== "pipx"

```bash
pipx install gunicorn
```

=== "Docker"

```bash
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](guides/docker.md) for production configurations.

=== "System Packages"

**Debian/Ubuntu:**
```bash
sudo apt-get update
sudo apt-get install gunicorn
```

**Fedora:**
```bash
sudo dnf install python3-gunicorn
```

**Arch Linux:**
```bash
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"

```bash
pip install gunicorn[gevent]
```

Run with:
```bash
gunicorn app:app --worker-class gevent
```

=== "ASGI (asyncio)"

No extra installation required:

```bash
gunicorn app:app --worker-class asgi
```

For better performance, install uvloop:
```bash
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

3.3 KiB Raw Blame History