Gunicorn is maintained by volunteers. If it powers your production, please consider supporting us:
## License
Gunicorn is released under the MIT License. See the [LICENSE](https://github.com/benoitc/gunicorn/blob/master/LICENSE) file for details.
---
### Overview (`docs/README.md`)
# Generate Documentation
## Requirements
Install the documentation dependencies with:
```bash
pip install -r requirements_dev.txt
```
This provides MkDocs with the Material theme and supporting plugins.
## Build static HTML
```bash
mkdocs build
```
The rendered site is emitted into the `site/` directory.
## Preview locally
```bash
mkdocs serve
```
This serves the documentation at http://127.0.0.1:8000/ with live reload.
---
### Overview (`examples/celery_alternative/README.md`)
# Celery Alternative Example
This example demonstrates how to replace Celery with Gunicorn's **dirty arbiters** for background task processing, using **async ASGI** for non-blocking HTTP handling.
## Why Use This Instead of Celery?
### The Problem with Celery
Celery requires:
- An external message broker (Redis or RabbitMQ)
- Separate worker processes (`celery -A app worker`)
- Stateless workers that reload models/connections on every task
- Polling or WebSockets for progress updates
### What Dirty Arbiters Provide
| Feature | Celery | Dirty Arbiters |
|---------|--------|----------------|
| **External broker** | Required (Redis/RabbitMQ) | None - uses Unix sockets |
| **Deployment** | Multiple processes | Single `gunicorn` command |
| **Worker state** | Stateless | Stateful - keep ML models, DB connections loaded |
| **Progress updates** | Polling or WebSocket | Native streaming |
| **HTTP blocking** | N/A (separate process) | Non-blocking with async ASGI |
### When to Use Dirty Arbiters
**Good fit:**
- Tasks that benefit from keeping state (ML models, DB connection pools, caches)
- Tasks where you want immediate results (not fire-and-forget)
- Real-time progress streaming
- Simpler deployment without external dependencies
**Not ideal for:**
- True fire-and-forget queuing with persistence
- Distributed task execution across multiple machines
- Tasks that must survive server restarts
## How It Works
```
/* Detailed source-code truncated for AI context efficiency. */
```
**Key insight:** The HTTP workers use async I/O, so `await client.execute_async()` doesn't block the event loop. One ASGI worker can handle thousands of concurrent requests while waiting for dirty workers to complete tasks.
## Quick Start
### Local Development
```bash
# Install dependencies
pip install fastapi uvloop httpx pytest pytest-asyncio
pip install -e ../.. # Install gunicorn from source
# Run the application
gunicorn -c gunicorn_conf.py app:app
# In another terminal, test it
curl http://localhost:8000/health
curl -X POST http://localhost:8000/api/email/send \
-H "Content-Type: application/json" \
-d '{"to": "test@example.com", "subject": "Hello", "body": "World"}'
# Interactive API docs
open http://localhost:8000/docs
```
### Docker
```bash
# Build and run
docker compose up --build
# Run with tests
docker compose --profile test up --build --abort-on-container-exit
```
## Task Workers
Each worker class maintains state across requests:
### EmailWorker (2 workers)
- Keeps SMTP connection alive
- `send_email(to, subject, body)` - Send single email
- `send_bulk_emails(recipients, subject, body)` - Bulk send with streaming progress
### ImageWorker (2 workers)
- Keeps PIL/image libraries loaded
- `resize(image_data, width, height)` - Resize image
- `process_batch(images, operation)` - Batch process with streaming
### DataWorker (4 workers)
- Maintains DB connection pool and query cache
- `aggregate(data, group_by, agg_field)` - Aggregate data
- `etl_pipeline(source_data, transformations)` - ETL with streaming progress
- `cached_query(query_key, ttl)` - Query with in-memory caching
### ScheduledWorker (1 worker)
- For periodic tasks (call from cron)
- `cleanup_old_files(directory, max_age_days)`
- `generate_daily_report()`
## Streaming Progress Example
Real-time progress without polling:
```python
import httpx
import json
async with httpx.AsyncClient() as client:
async with client.stream(
"POST",
"http://localhost:8000/api/email/send-bulk",
json={
"recipients": ["a@x.com", "b@x.com", "c@x.com"],
"subject": "Newsletter",
"body": "Hello!",
},
) as response:
async for line in response.aiter_lines():
if line.startswith("data: "):
progress = json.loads(line[6:])
if progress["type"] == "progress":
print(f"Progress: {progress['percent']}%")
elif progress["type"] == "complete":
print(f"Done! Sent: {progress['sent']}")
```
## Celery Migration Guide
### Before (Celery)
```python
# tasks.py
from celery import Celery
app = Celery('tasks', broker='redis://localhost')
@app.task
def send_email(to, subject, body):
smtp = smtplib.SMTP(...) # New connection every task!
smtp.send(...)
return {"status": "sent"}
@app.task(bind=True)
def send_bulk(self, recipients, subject, body):
for i, to in enumerate(recipients):
send_email(to, subject, body)
self.update_state(state='PROGRESS', meta={'current': i}) # Requires polling!
```
```python
# views.py - Flask
from tasks import send_email
@app.route('/send')
def send_view():
send_email.delay(to, subject, body) # Fire and forget
return {"status": "queued"} # Can't get result without polling
```
### After (Dirty Arbiters)
```python
# tasks.py
from gunicorn.dirty.app import DirtyApp
class EmailWorker(DirtyApp):
workers = 2
def init(self):
self.smtp = smtplib.SMTP(...) # Connected once, reused!
def __call__(self, action, *args, **kwargs):
return getattr(self, action)(*args, **kwargs)
def send_email(self, to, subject, body):
self.smtp.send(...) # Reuses connection
return {"status": "sent"}
def send_bulk(self, recipients, subject, body):
for i, to in enumerate(recipients):
self.send_email(to, subject, body)
yield {"type": "progress", "current": i} # Native streaming!
```
```python
# views.py - FastAPI (async)
from gunicorn.dirty import get_dirty_client_async
@app.post('/send')
async def send_view(data: EmailRequest):
client = await get_dirty_client_async()
# Non-blocking! Other requests handled while waiting
result = await client.execute_async("tasks:EmailWorker", "send_email", ...)
return result # Immediate result, no polling!
```
## Configuration
```python
# gunicorn_conf.py
# ASGI workers for non-blocking HTTP
worker_class = "asgi"
asgi_loop = "uvloop"
workers = 4
# Dirty workers (replace Celery)
dirty_apps = [
"tasks:EmailWorker",
"tasks:ImageWorker",
"tasks:DataWorker",
]
dirty_workers = 9
dirty_timeout = 300
```
## Running Tests
```bash
# Unit tests (no server needed)
pytest tests/test_tasks.py -v
# Integration tests (server must be running)
APP_URL=http://localhost:8000 pytest tests/test_integration.py -v
# All tests via Docker
docker compose --profile test up --build --abort-on-container-exit
```
## API Endpoints
Visit `/docs` for interactive Swagger documentation.
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/email/send` | POST | Send single email |
| `/api/email/send-bulk` | POST | Bulk send (SSE streaming) |
| `/api/image/resize` | POST | Resize image |
| `/api/image/process-batch` | POST | Batch process (SSE streaming) |
| `/api/data/aggregate` | POST | Aggregate data |
| `/api/data/etl` | POST | ETL pipeline (SSE streaming) |
| `/api/data/query` | POST | Cached query |
| `/api/scheduled/*` | POST | Scheduled tasks |
| `/health` | GET | Health check |
---
### Overview (`examples/embedding_service/README.md`)
# Embedding Service Example
A FastAPI-based text embedding service using sentence-transformers, powered by
gunicorn's dirty workers for efficient ML model management.
## Overview
This example demonstrates how to build a production-ready embedding API that:
- Keeps ML models loaded in memory across requests (dirty workers)
- Handles HTTP efficiently with async FastAPI (ASGI workers)
- Provides batch embedding for multiple texts
- Includes Docker-based deployment and testing
## Architecture
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ HTTP Clients │────►│ FastAPI (ASGI) │────►│ DirtyWorker │
│ │ │ - /embed │ │ - sentence- │
│ │◄────│ - /health │◄────│ transformers │
└─────────────────┘ └──────────────────┘ │ - Model in memory │
└─────────────────────┘
```
**Why dirty workers?**
- ML models are expensive to load (several seconds)
- Dirty workers load the model once at startup
- HTTP workers remain lightweight and responsive
- Model stays in memory, serving many requests
## Quick Start
### With Docker (recommended)
```bash
cd examples/embedding_service
docker compose up --build
```
### Local Development
```bash
# Install dependencies
pip install sentence-transformers fastapi pydantic
# Run with gunicorn
gunicorn examples.embedding_service.main:app \
-c examples/embedding_service/gunicorn_conf.py
```
## API Reference
### POST /embed
Generate embeddings for a list of texts.
**Request:**
```json
{
"texts": ["Hello world", "Another sentence"]
}
```
**Response:**
```json
{
"embeddings": [
[0.123, -0.456, ...],
[0.789, -0.012, ...]
]
}
```
**Example:**
```bash
curl -X POST http://localhost:8000/embed \
-H "Content-Type: application/json" \
-d '{"texts": ["Hello world"]}'
```
### GET /health
Health check endpoint.
**Response:**
```json
{"status": "ok"}
```
## Configuration
Edit `gunicorn_conf.py` to adjust:
| Setting | Default | Description |
|---------|---------|-------------|
| `workers` | 2 | Number of HTTP workers |
| `dirty_workers` | 1 | Number of ML model workers |
| `dirty_timeout` | 60 | Max seconds per inference |
| `bind` | 0.0.0.0:8000 | Listen address |
## Model
Uses [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2):
- 384-dimensional embeddings
- Fast inference (~14K sentences/sec on GPU)
- Good quality for semantic search
- ~90MB download
To use a different model, edit `embedding_app.py`:
```python
self.model = SentenceTransformer('your-model-name')
```
## Testing
Run the integration tests:
```bash
# Start the service first
docker compose up -d
# Run tests
pip install requests numpy
python test_embedding.py
```
## Production Considerations
1. **GPU Support**: Add CUDA to the Dockerfile for faster inference
2. **Scaling**: Increase `dirty_workers` for more concurrent embeddings
3. **Caching**: Add Redis caching for repeated texts
4. **Rate Limiting**: Add FastAPI middleware for rate limiting
5. **Monitoring**: Add Prometheus metrics endpoint
---
### Overview (`examples/http2_gevent/README.md`)
# HTTP/2 with Gevent Worker Example
This example demonstrates how to run Gunicorn with HTTP/2 support using the gevent async worker.
## Features
- HTTP/2 protocol with ALPN negotiation
- Gevent-based async worker for high concurrency
- Connection multiplexing (multiple streams per connection)
- Flow control for large transfers
- SSL/TLS encryption (required for HTTP/2)
## Quick Start
### 1. Generate SSL Certificates
HTTP/2 requires TLS. Generate self-signed certificates for testing:
```bash
chmod +x generate_certs.sh
./generate_certs.sh
```
### 2. Start with Docker Compose
```bash
docker compose up -d
```
### 3. Test the Server
Using curl with HTTP/2:
```bash
# Basic request
curl -k --http2 https://localhost:8443/
# Check HTTP version
curl -k --http2 -w "HTTP Version: %{http_version}\n" https://localhost:8443/
# Test echo endpoint
curl -k --http2 -X POST -d "Hello HTTP/2" https://localhost:8443/echo
# Get server info
curl -k --http2 https://localhost:8443/info | jq
```
### 4. Run Tests
```bash
# Install test dependencies
pip install httpx[http2] pytest pytest-asyncio
# Run tests
python test_http2_gevent.py
# Or with pytest for more detail
pytest test_http2_gevent.py -v
```
## Running Locally (Without Docker)
### Prerequisites
```bash
pip install gunicorn[gevent,http2]
```
### Generate Certificates
```bash
./generate_certs.sh
```
### Start Server
```bash
gunicorn --config gunicorn_conf.py app:app
```
Or with command-line options:
```bash
gunicorn app:app \
--bind 0.0.0.0:8443 \
--worker-class gevent \
--workers 4 \
--worker-connections 1000 \
--http-protocols h2,h1 \
--certfile certs/server.crt \
--keyfile certs/server.key
```
## Configuration Options
### HTTP/2 Settings
| Setting | Default | Description |
|---------|---------|-------------|
| `http_protocols` | `['h1']` | Enable protocols: `['h2', 'h1']` for HTTP/2 |
| `http2_max_concurrent_streams` | 100 | Max streams per connection |
| `http2_initial_window_size` | 65535 | Flow control window size (bytes) |
| `http2_max_frame_size` | 16384 | Max frame size (bytes) |
| `http2_max_header_list_size` | 65536 | Max header list size (bytes) |
### Gevent Worker Settings
| Setting | Default | Description |
|---------|---------|-------------|
| `worker_class` | `sync` | Set to `gevent` for async |
| `workers` | 1 | Number of worker processes |
| `worker_connections` | 1000 | Max clients per worker |
## Endpoints
| Path | Method | Description |
|------|--------|-------------|
| `/` | GET | Hello message |
| `/health` | GET | Health check |
| `/echo` | POST | Echo request body |
| `/info` | GET | Server/request info as JSON |
| `/large` | GET | 1MB response (test streaming) |
| `/stream` | GET | Server-sent events stream |
| `/delay?seconds=N` | GET | Delayed response |
| `/priority` | GET | HTTP/2 priority info |
## Performance Tips
1. **Worker Count**: Use `2 * CPU cores + 1` workers for I/O-bound apps
2. **Connections**: Increase `worker_connections` for high concurrency
3. **Window Size**: Larger `http2_initial_window_size` improves throughput for large transfers
4. **Streams**: Increase `http2_max_concurrent_streams` for many parallel requests
## Troubleshooting
### Certificate Issues
```bash
# Regenerate certificates
rm -rf certs/
./generate_certs.sh
```
### Connection Refused
```bash
# Check if server is running
docker compose ps
# View logs
docker compose logs -f
```
### HTTP/2 Not Negotiated
Ensure:
- SSL/TLS is configured (certfile and keyfile)
- `http_protocols` includes `'h2'`
- Client supports HTTP/2 over TLS (curl with `--http2`, not `--http2-prior-knowledge`)
## License
MIT License - See the main Gunicorn repository for details.
---
### Overview (`examples/streaming_chat/README.md`)
# Streaming Chat Example
A FastAPI-based chat demo that simulates LLM token-by-token streaming, powered
by Gunicorn's dirty workers for efficient long-running operations.
## Overview
This example demonstrates how to build a streaming chat API that:
- Streams tokens word-by-word like ChatGPT (Server-Sent Events)
- Uses dirty workers for the "inference" workload
- Includes a browser-based chat UI for testing
- Requires no ML dependencies (simulated responses)
## Architecture
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ Browser/curl │────►│ FastAPI (ASGI) │────►│ DirtyWorker │
│ SSE stream │ │ - /chat (SSE) │ │ - ChatApp │
│ │◄────│ - /chat/sync │◄────│ - Token generator │
└─────────────────┘ └──────────────────┘ └─────────────────────┘
│
▼
text/event-stream
data: {"token": "Hello"}
data: {"token": " "}
data: {"token": "world"}
data: [DONE]
```
**Why streaming with dirty workers?**
- Real LLM inference is slow (seconds to minutes)
- Users expect to see responses appear gradually
- Dirty workers keep the "model" loaded between requests
- HTTP workers remain responsive during streaming
## Quick Start
### With Docker (recommended)
```bash
cd examples/streaming_chat
docker compose up --build
```
Then open http://localhost:8000 in your browser.
### Local Development
```bash
# Install dependencies
pip install fastapi pydantic
# Run with gunicorn
gunicorn examples.streaming_chat.main:app \
-c examples/streaming_chat/gunicorn_conf.py
```
## API Reference
### POST /chat
Stream a chat response using Server-Sent Events.
**Request:**
```json
{
"prompt": "hello",
"thinking": false
}
```
**Response:** `text/event-stream`
```
data: {"token": "Hello"}
data: {"token": "!"}
data: {"token": " "}
data: {"token": "I'm"}
...
data: [DONE]
```
**Example with curl:**
```bash
curl -N http://localhost:8000/chat \
-H "Content-Type: application/json" \
-d '{"prompt": "hello"}'
```
### POST /chat/sync
Non-streaming version that returns the complete response.
**Request:**
```json
{
"prompt": "hello"
}
```
**Response:**
```json
{
"response": "Hello! I'm a simulated AI assistant..."
}
```
### GET /health
Health check endpoint.
**Response:**
```json
{"status": "ok"}
```
### GET /
Browser-based chat UI for testing.
## Configuration
Edit `gunicorn_conf.py` to adjust:
| Setting | Default | Description |
|---------|---------|-------------|
| `workers` | 2 | Number of HTTP workers |
| `dirty_workers` | 1 | Number of dirty workers |
| `dirty_timeout` | 60 | Max seconds per request |
| `bind` | 0.0.0.0:8000 | Listen address |
## Prompts
The simulated chat app responds to these keywords:
| Keyword | Response |
|---------|----------|
| `hello`, `hi`, `hey` | Greeting message |
| `explain` | Explanation of dirty workers |
| `streaming` | How streaming works |
| `code` | Example code snippet |
| (default) | Generic thoughtful response |
## Features Demonstrated
1. **Token streaming** - Word-by-word output via generators
2. **SSE protocol** - Browser-compatible event streaming
3. **Async generators** - Using `stream_async()` from dirty client
4. **Thinking mode** - Multi-phase streaming with visible "thinking"
5. **Browser UI** - Interactive chat with cursor animation
## Testing
Run the integration tests:
```bash
# Start the service first
docker compose up -d
# Run tests
pip install requests
python test_streaming.py
```
## Adapting for Real LLMs
To use a real LLM instead of simulated responses:
```python
# chat_app.py
from gunicorn.dirty.app import DirtyApp
class ChatApp(DirtyApp):
def init(self):
from transformers import pipeline
self.generator = pipeline("text-generation", model="gpt2")
def generate(self, prompt):
for output in self.generator(prompt, max_new_tokens=100, do_sample=True):
# Yield tokens as they're generated
yield output["generated_text"]
def close(self):
del self.generator
```
Or with an API-based LLM:
```python
class ChatApp(DirtyApp):
def init(self):
import openai
self.client = openai.OpenAI()
async def generate(self, prompt):
stream = self.client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": prompt}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
yield chunk.choices[0].delta.content
```
## Production Considerations
1. **Real LLM**: Replace `ChatApp` with actual model inference
2. **GPU Support**: Add CUDA to Dockerfile for faster inference
3. **Rate Limiting**: Add FastAPI middleware for rate limiting
4. **Authentication**: Add API key validation
5. **Monitoring**: Add Prometheus metrics endpoint
6. **Timeouts**: Adjust `dirty_timeout` based on max response length
---
### Overview (`tests/docker/README.md`)
# Docker integration tests
End-to-end suites that run gunicorn in containers, some behind nginx. Use these
when a change touches process management, protocol behavior on the wire, or
anything that only shows up with a real client and a real proxy in front.
## Running them
```sh
PYTEST=".venv/bin/python -m pytest" scripts/run_docker_tests.sh
```
One suite at a time:
```sh
PYTEST=".venv/bin/python -m pytest" scripts/run_docker_tests.sh uwsgi http2
```
Requires a running Docker daemon. The first run builds images and is slow;
later runs reuse them.
## Do not run them with a single pytest invocation
`pytest tests/docker` looks like it should work and does not. Every suite ships
its own `docker-compose.yml` and binds fixed host ports, so running them
together means each suite's requests can reach another suite's containers. The
result is failures that have nothing to do with the code: assertion errors from
valid responses served by the wrong application, not connection errors.
`tests/docker` is listed in `norecursedirs` in `pyproject.toml`, so a plain
`pytest tests/` skips these entirely and reports success without running any of
them. That is deliberate, but worth knowing before you conclude the suite is
green.
Use `scripts/run_docker_tests.sh`, which runs each suite on its own and tears
its stack down before starting the next.
## Ports
The suites bind fixed host ports. Anything else already listening on one of them
will silently answer the tests instead of the container. `mkdocs serve` defaults
to 8000 and collides with `asgi_compliance`.
| Suite | Host ports |
| --- | --- |
| `asgi_compliance` | 8000, 8080, 8443, 8444, 8445 |
| `asgi_framework_compat` | 8001 to 8006 |
| `http2` | 8443, 8444 |
| `h2spec` | 8451, 8452, 8453 |
| `stress` | 8460 to 8466, 8474, 8475 |
| `uwsgi` | 8080 |
If a suite fails everywhere at once, check for a port collision before looking
at the code:
```sh
lsof -nP -iTCP:8000 -sTCP:LISTEN
```
## Suites
| Directory | Covers |
| --- | --- |
| `asgi_compliance` | ASGI HTTP, websocket, lifespan and streaming behavior |
| `asgi_framework_compat` | Django, FastAPI, Starlette, Quart, Litestar, BlackSheep |
| `dirty_arbiter` | dirty arbiter lifecycle, parent death, respawn |
| `dirty_ttin_ttou` | scaling dirty workers with TTIN/TTOU |
| `http2` | HTTP/2 over TLS, direct and behind nginx |
| `per_app_allocation` | per-app worker allocation end to end |
| `stress` | k6 load and resilience across workers, direct and behind nginx |
| `uwsgi` | uWSGI binary protocol behind nginx |
`asgi/` and `test_asgi_uwsgi/` are shell-driven demos (`test_asgi.sh`,
`test_uwsgi.sh`), not pytest suites, and the runner skips them.
## CI
`.github/workflows/docker-integration.yml` runs `uwsgi`, `h2spec`, and the
`stress` smoke matrix. The heavier `stress` resilience and fault scenarios run
in `.github/workflows/stress-nightly.yml`. The other suites are not gated, so
run them locally before changing the areas they cover.
## Certificates
`asgi_compliance` and `http2` generate self-signed certificates into their
`certs/` directories, regenerating them once a day. They will show as modified
in `git status` after a run. Do not commit them.
---
### Overview (`tests/docker/asgi_framework_compat/README.md`)
# ASGI Framework Compatibility Test Suite
This test suite validates gunicorn's native ASGI worker (`-k asgi`) against
multiple ASGI frameworks to ensure protocol compliance.
## Frameworks Tested
| Framework | Description |
|-----------|-------------|
| Django + Channels | Django with Channels for WebSocket |
| FastAPI | Modern, fast API framework (Starlette-based) |
| Starlette | Pure ASGI framework |
| Quart | Flask-like async framework |
| Litestar | Modern ASGI framework |
| BlackSheep | High-performance ASGI framework |
## Test Categories
- **HTTP Scope**: ASGI 3.0 HTTP scope compliance
- **HTTP Messages**: Request/response message handling
- **WebSocket**: WebSocket protocol compliance
- **Lifespan**: Startup/shutdown lifecycle
- **Streaming**: Chunked responses and SSE
## Quick Start
```bash
# Build and start all framework containers
docker compose up -d --build
# Run tests
pip install -r requirements.txt
pytest tests/ -v
# Generate compatibility grid
python scripts/generate_grid.py
```
## Testing Event Loop Variants
```bash
# Test with auto-detection (uvloop if available)
ASGI_LOOP=auto docker compose up -d --build
pytest tests/ -v
# Test with asyncio only
ASGI_LOOP=asyncio docker compose up -d --build
pytest tests/ -v
# Test with uvloop explicitly
ASGI_LOOP=uvloop docker compose up -d --build
pytest tests/ -v
# Generate combined report for both loop types
python scripts/generate_grid.py --loop both
```
## Single Framework Testing
```bash
# Test only FastAPI
pytest tests/ -v --framework fastapi
# Test only Django
pytest tests/ -v --framework django
```
## Directory Structure
```
asgi_framework_compat/
├── conftest.py # Test fixtures
├── docker-compose.yml # Container orchestration
├── requirements.txt # Test dependencies
├── frameworks/
│ ├── contract.py # Endpoint contract
│ ├── django_app/ # Django implementation
│ ├── fastapi_app/ # FastAPI implementation
│ ├── starlette_app/ # Starlette implementation
│ ├── quart_app/ # Quart implementation
│ ├── litestar_app/ # Litestar implementation
│ └── blacksheep_app/ # BlackSheep implementation
├── tests/
│ ├── test_http_scope.py
│ ├── test_http_messages.py
│ ├── test_websocket_scope.py
│ ├── test_lifespan_scope.py
│ └── test_streaming.py
├── scripts/
│ └── generate_grid.py # Compatibility matrix
└── results/ # Generated reports
```
## Container Management
```bash
# Start containers
docker compose up -d --build
# View logs
docker compose logs -f
# Stop containers
docker compose down
# Rebuild specific framework
docker compose build fastapi
docker compose up -d fastapi
```
## Results
After running `generate_grid.py`, check the `results/` directory for:
- `compatibility_grid_*.md` - Markdown compatibility matrices
- `compatibility_grid_*.json` - JSON data for programmatic access
---
### Overview (`tests/docker/dirty_arbiter/README.md`)
# Docker-Based Dirty Arbiter Integration Tests
This directory contains Docker-based integration tests that verify the dirty
arbiter process lifecycle under realistic conditions.
## Overview
These tests verify:
1. **Parent Death Detection**: Dirty arbiter self-terminates when main arbiter
dies unexpectedly (SIGKILL)
2. **Orphan Cleanup**: Old dirty arbiter processes are cleaned up on restart
3. **Respawning**: Main arbiter respawns dirty arbiter when it crashes
4. **Graceful Shutdown**: Both arbiters exit cleanly on SIGTERM
## Prerequisites
- Docker
- Python 3.10+
- pytest
## Quick Start
```bash
# Build the Docker image
docker compose build
# Run all tests
pytest test_parent_death.py -v
# Run specific test
pytest test_parent_death.py::TestParentDeath::test_dirty_arbiter_exits_on_parent_sigkill -v
```
## Manual Verification
You can manually verify the behavior:
```bash
# Start the container
docker compose up -d
# Check running processes
docker exec dirty_arbiter-gunicorn-1 ps aux | grep gunicorn
# SIGKILL the master and watch dirty arbiter exit
MASTER_PID=$(docker exec dirty_arbiter-gunicorn-1 pgrep -f "gunicorn: master")
docker exec dirty_arbiter-gunicorn-1 kill -9 $MASTER_PID
# After ~2 seconds, check that all gunicorn processes exited
docker exec dirty_arbiter-gunicorn-1 ps aux | grep gunicorn
# View logs
docker logs dirty_arbiter-gunicorn-1
# Cleanup
docker compose down
```
## Test Scenarios
### Scenario 1: Parent SIGKILL
Tests that the dirty arbiter detects parent death via ppid check:
1. Start gunicorn with dirty workers
2. SIGKILL the main arbiter (bypasses graceful shutdown)
3. Verify dirty arbiter detects ppid change within ~2 seconds
4. Verify no orphan processes remain
### Scenario 2: Orphan Cleanup
Tests the `_cleanup_orphaned_dirty_arbiter()` mechanism:
1. Start gunicorn, note dirty arbiter PID
2. SIGKILL main arbiter (dirty arbiter becomes orphan)
3. Restart gunicorn
4. Verify old dirty arbiter was cleaned up
5. Verify new dirty arbiter spawned
### Scenario 3: Dirty Arbiter Respawn
Tests that main arbiter respawns a dead dirty arbiter:
1. Start gunicorn
2. SIGKILL the dirty arbiter
3. Wait for respawn (~1-2 seconds)
4. Verify new dirty arbiter is running
### Scenario 4: Graceful Shutdown
Tests clean shutdown via SIGTERM:
1. Start gunicorn with dirty workers
2. SIGTERM the main arbiter
3. Verify both arbiters exit cleanly within graceful_timeout
4. Verify clean exit logs
## Files
| File | Description |
|------|-------------|
| `Dockerfile` | Container build configuration |
| `docker-compose.yml` | Container orchestration |
| `app.py` | Simple WSGI app with TestDirtyApp |
| `gunicorn_conf.py` | Gunicorn configuration |
| `test_parent_death.py` | pytest integration tests |
| `README.md` | This file |
## Configuration
The `gunicorn_conf.py` uses:
- 1 sync worker
- 1 dirty worker
- 5 second graceful timeout (for faster tests)
- Debug logging
## Expected Log Messages
When verifying behavior, look for these log messages:
| Message | Meaning |
|---------|---------|
| `Parent changed, shutting down dirty arbiter` | ppid detection triggered |
| `Killing orphaned dirty arbiter` | Orphan cleanup activated |
| `Spawning dirty arbiter` | New dirty arbiter being created |
| `Dirty arbiter exiting` | Clean shutdown |
## Troubleshooting
**Tests time out waiting for container**:
- Check Docker is running
- Check no port conflicts on 8000
- Try `docker compose down` and rebuild
**Dirty arbiter doesn't exit after parent death**:
- Check ppid detection is working (logs should show check)
- The check runs every 1 second, so allow 2-3 seconds
**Container logs not showing expected messages**:
- Verify loglevel is set to "debug" in gunicorn_conf.py
- Check `docker logs 
Battle-tested. Production-ready. One command to serve your Python apps.
Trusted by thousands of companies. The pre-fork worker model handles traffic spikes gracefully.
Minimal dependencies, simple configuration. Efficient from containers to bare metal.
Works with any WSGI or ASGI framework. Django, Flask, FastAPI—it just runs.
WSGI and ASGI frameworks, no changes needed
Powering Python apps since 2010. Support continued development.
Become a SponsorSponsored by
---
### Content Uwsgi (`docs/content/uwsgi.md`)
# uWSGI Protocol
Gunicorn supports the uWSGI binary protocol, allowing it to receive requests from
nginx using the `uwsgi_pass` directive. This provides efficient communication
between nginx and Gunicorn without HTTP overhead.
Both **WSGI** and **ASGI** workers support the uWSGI protocol.
!!! note
This is the **uWSGI binary protocol**, not the uWSGI server. Gunicorn
implements the protocol to receive requests from nginx, similar to how
the uWSGI server would.
## Quick Start
Enable uWSGI protocol support:
```bash
# WSGI application
gunicorn myapp:app --protocol uwsgi --bind 127.0.0.1:8000
# ASGI application
gunicorn myapp:app --worker-class asgi --protocol uwsgi --bind 127.0.0.1:8000
```
Configure nginx to forward requests:
```nginx
upstream gunicorn {
server 127.0.0.1:8000;
}
server {
listen 80;
server_name example.com;
location / {
uwsgi_pass gunicorn;
include uwsgi_params;
}
}
```
## Why Use uWSGI Protocol?
The uWSGI binary protocol offers several advantages over HTTP proxying:
- **Lower overhead** - Binary format is more compact than HTTP headers
- **Better integration** - nginx's native uwsgi module is highly optimized
- **Simpler configuration** - No need to reconstruct HTTP headers
## Configuration
### Protocol Setting
Switch from HTTP to uWSGI protocol:
```bash
gunicorn myapp:app --protocol uwsgi
```
Or in a configuration file:
```python
# gunicorn.conf.py
protocol = "uwsgi"
```
### Allowed IPs
By default, uWSGI protocol requests are only accepted from localhost
(`127.0.0.1` and `::1`). This prevents unauthorized hosts from sending
requests directly to Gunicorn.
To allow additional IPs:
```bash
gunicorn myapp:app --protocol uwsgi --uwsgi-allow-from 10.0.0.1,10.0.0.2
```
To allow all IPs (not recommended for production):
```bash
gunicorn myapp:app --protocol uwsgi --uwsgi-allow-from '*'
```
!!! warning
Only allow IPs from trusted sources. The uWSGI protocol does not provide
authentication, so anyone who can connect can send requests.
!!! note
UNIX socket connections are always allowed regardless of this setting.
### Using UNIX Sockets
For better performance and security, use UNIX sockets instead of TCP:
```bash
gunicorn myapp:app --protocol uwsgi --bind unix:/run/gunicorn.sock
```
Nginx configuration:
```nginx
upstream gunicorn {
server unix:/run/gunicorn.sock;
}
server {
listen 80;
location / {
uwsgi_pass gunicorn;
include uwsgi_params;
}
}
```
## Nginx Configuration
### Basic Setup
Create or verify the `uwsgi_params` file exists (usually at `/etc/nginx/uwsgi_params`):
```nginx
uwsgi_param QUERY_STRING $query_string;
uwsgi_param REQUEST_METHOD $request_method;
uwsgi_param CONTENT_TYPE $content_type;
uwsgi_param CONTENT_LENGTH $content_length;
uwsgi_param REQUEST_URI $request_uri;
uwsgi_param PATH_INFO $document_uri;
uwsgi_param DOCUMENT_ROOT $document_root;
uwsgi_param SERVER_PROTOCOL $server_protocol;
uwsgi_param REQUEST_SCHEME $scheme;
uwsgi_param HTTPS $https if_not_empty;
uwsgi_param REMOTE_ADDR $remote_addr;
uwsgi_param REMOTE_PORT $remote_port;
uwsgi_param SERVER_PORT $server_port;
uwsgi_param SERVER_NAME $server_name;
```
### With SSL Termination
When nginx handles SSL and forwards to Gunicorn:
```nginx
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
uwsgi_pass gunicorn;
include uwsgi_params;
uwsgi_param HTTPS on;
}
}
```
### Load Balancing
Distribute requests across multiple Gunicorn instances:
```nginx
upstream gunicorn {
least_conn;
server 127.0.0.1:8000;
server 127.0.0.1:8001;
server 127.0.0.1:8002;
}
server {
listen 80;
location / {
uwsgi_pass gunicorn;
include uwsgi_params;
}
}
```
### Static Files
Serve static files directly from nginx:
```nginx
server {
listen 80;
location /static/ {
alias /path/to/static/;
}
location / {
uwsgi_pass gunicorn;
include uwsgi_params;
}
}
```
## Protocol Details
The uWSGI protocol uses a compact binary format:
| Bytes | Field | Description |
|-------|-------|-------------|
| 0 | modifier1 | Packet type (0 = WSGI request) |
| 1-2 | datasize | Size of vars block (little-endian) |
| 3 | modifier2 | Additional flags (usually 0) |
After the header, the vars block contains CGI-style key-value pairs:
```
[2-byte key_size][key][2-byte val_size][value]...
```
Standard CGI variables like `REQUEST_METHOD`, `PATH_INFO`, and `QUERY_STRING`
are extracted from this block to construct the WSGI environ.
## Combining with HTTP
You can run Gunicorn with both HTTP and uWSGI protocol support by running
separate instances:
```bash
# HTTP for direct access
gunicorn myapp:app --bind 127.0.0.1:8080
# uWSGI for nginx
gunicorn myapp:app --protocol uwsgi --bind 127.0.0.1:8000
```
## Troubleshooting
### ForbiddenUWSGIRequest Error
If you see "Forbidden uWSGI request from IP", the connecting IP is not in
the allowed list. Either:
1. Add the IP to `--uwsgi-allow-from`
2. Use UNIX sockets instead
3. Ensure nginx is connecting from an allowed IP
### Invalid uWSGI Header
This usually means:
1. HTTP traffic is being sent to a uWSGI endpoint
2. The packet is malformed or truncated
3. Network issues caused data corruption
Verify that nginx is using `uwsgi_pass` (not `proxy_pass`) and that the
`uwsgi_params` file is being included.
### Headers Missing
If certain headers aren't reaching your application, verify they're included
in `uwsgi_params`. Custom headers should be passed as:
```nginx
uwsgi_param HTTP_X_CUSTOM_HEADER $http_x_custom_header;
```
## See Also
- [Settings Reference](reference/settings.md#protocol) - Protocol and uWSGI settings
- [Deploy](deploy.md) - General deployment guidance
- [Design](design.md) - Worker architecture overview
---
### Content Guides Docker (`docs/content/guides/docker.md`)
# Docker Deployment
Running Gunicorn in Docker containers is the most common deployment pattern
for modern Python applications. This guide covers best practices for
containerizing Gunicorn applications.
## Official Docker Image
Gunicorn provides an official Docker image on GitHub Container Registry:
```bash
docker pull ghcr.io/benoitc/gunicorn:latest
```
### Quick Start
Mount your application directory and run:
```bash
docker run -p 8000:8000 -v $(pwd):/app ghcr.io/benoitc/gunicorn app:app
```
### Running in Background
Use `-d` (detached mode) to run the container in the background:
```bash
# Start in background
docker run -d --name myapp -p 8000:8000 -v $(pwd):/app ghcr.io/benoitc/gunicorn app:app
# View logs
docker logs myapp
# Follow logs in real-time
docker logs -f myapp
# Stop the container
docker stop myapp
# Start it again
docker start myapp
# Remove the container
docker rm myapp
```
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `GUNICORN_BIND` | Full bind address | `0.0.0.0:8000` |
| `GUNICORN_HOST` | Bind host | `0.0.0.0` |
| `GUNICORN_PORT` | Bind port | `8000` |
| `GUNICORN_WORKERS` | Number of workers | `(2 * CPU) + 1` |
| `GUNICORN_ARGS` | Additional arguments | (none) |
### With Configuration
```bash
docker run -p 9000:9000 -v $(pwd):/app \
-e GUNICORN_PORT=9000 \
-e GUNICORN_WORKERS=4 \
-e GUNICORN_ARGS="--timeout 120 --access-logfile -" \
ghcr.io/benoitc/gunicorn app:app
```
### As Base Image (Recommended for Production)
```dockerfile
FROM ghcr.io/benoitc/gunicorn:24.1.0
# Install app dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Copy application
COPY --chown=gunicorn:gunicorn . .
CMD ["myapp:app", "--workers", "4"]
```
### With Docker Compose
```yaml
services:
web:
image: ghcr.io/benoitc/gunicorn:latest
ports:
- "8000:8000"
volumes:
- ./app:/app
command: ["myapp:app", "--workers", "4"]
```
### Available 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
## Building Your Own Image
For more control, build a custom image using the patterns below.
## Basic Dockerfile
```dockerfile
FROM python:3.12-slim
WORKDIR /app
# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Copy application
COPY . .
# Run gunicorn
CMD ["gunicorn", "app:app", "--bind", "0.0.0.0:8000"]
```
Build and run:
```bash
docker build -t myapp .
docker run -p 8000:8000 myapp
```
## Production Configuration
### Environment Variables
Use environment variables for configuration:
```dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
# Configuration via environment
ENV GUNICORN_WORKERS=4
ENV GUNICORN_BIND=0.0.0.0:8000
CMD gunicorn app:app \
--workers ${GUNICORN_WORKERS} \
--bind ${GUNICORN_BIND}
```
Or use `GUNICORN_CMD_ARGS`:
```dockerfile
ENV GUNICORN_CMD_ARGS="--workers=4 --bind=0.0.0.0:8000"
CMD ["gunicorn", "app:app"]
```
### Worker Count
In containers, determine workers based on available CPU:
```python
# gunicorn.conf.py
import multiprocessing
workers = multiprocessing.cpu_count() * 2 + 1
bind = "0.0.0.0:8000"
```
Or let Kubernetes/Docker limit CPU and calculate accordingly:
```bash
# At runtime
gunicorn app:app --workers $(( 2 * $(nproc) + 1 ))
```
### Non-Root User
Run as a non-root user for security:
```dockerfile
FROM python:3.12-slim
# Create non-root user
RUN useradd --create-home appuser
WORKDIR /home/appuser/app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY --chown=appuser:appuser . .
USER appuser
CMD ["gunicorn", "app:app", "--bind", "0.0.0.0:8000"]
```
### Health Checks
Add a health check endpoint and Docker health check:
```dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8000/health || exit 1
```
## Multi-Stage Build
Reduce image size with multi-stage builds:
```dockerfile
# Build stage
FROM python:3.12 AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt
# Runtime stage
FROM python:3.12-slim
WORKDIR /app
# Copy wheels and install
COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir /wheels/* && rm -rf /wheels
COPY . .
CMD ["gunicorn", "app:app", "--bind", "0.0.0.0:8000", "--workers", "4"]
```
## Docker Compose
Example `docker-compose.yml`:
```yaml
services:
web:
build: .
ports:
- "8000:8000"
environment:
- DATABASE_URL=postgres://db:5432/myapp
depends_on:
- db
deploy:
resources:
limits:
cpus: '2'
memory: 512M
db:
image: postgres:15
environment:
- POSTGRES_DB=myapp
- POSTGRES_PASSWORD=secret
volumes:
- postgres_data:/var/lib/postgresql/data
nginx:
image: nginx:alpine
ports:
- "80:80"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
depends_on:
- web
volumes:
postgres_data:
```
## Kubernetes Deployment
Example Kubernetes deployment:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
spec:
replicas: 3
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp
spec:
containers:
- name: myapp
image: myapp:latest
ports:
- containerPort: 8000
env:
- name: GUNICORN_WORKERS
value: "4"
resources:
limits:
cpu: "1"
memory: "512Mi"
requests:
cpu: "500m"
memory: "256Mi"
livenessProbe:
httpGet:
path: /health
port: 8000
initialDelaySeconds: 10
periodSeconds: 10
readinessProbe:
httpGet:
path: /health
port: 8000
initialDelaySeconds: 5
periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
name: myapp
spec:
selector:
app: myapp
ports:
- port: 80
targetPort: 8000
```
## Graceful Shutdown
Gunicorn handles `SIGTERM` gracefully by default. Configure the timeout:
```dockerfile
CMD ["gunicorn", "app:app", \
"--bind", "0.0.0.0:8000", \
"--graceful-timeout", "30", \
"--timeout", "120"]
```
Match Docker's stop timeout:
```yaml
# docker-compose.yml
services:
web:
stop_grace_period: 30s
```
## Logging
Log to stdout/stderr for Docker log collection:
```python
# gunicorn.conf.py
accesslog = "-"
errorlog = "-"
loglevel = "info"
```
Use JSON logging for log aggregation:
```python
# gunicorn.conf.py
import json
import datetime
class JsonFormatter:
def format(self, record):
return json.dumps({
"timestamp": datetime.datetime.utcnow().isoformat(),
"level": record.levelname,
"message": record.getMessage(),
})
logconfig_dict = {
"version": 1,
"formatters": {
"json": {"()": JsonFormatter}
},
"handlers": {
"console": {
"class": "logging.StreamHandler",
"formatter": "json",
"stream": "ext://sys.stdout"
}
},
"root": {
"handlers": ["console"],
"level": "INFO"
}
}
```
## Troubleshooting
### Worker Timeout
If workers are killed with `[CRITICAL] WORKER TIMEOUT`, increase the timeout:
```bash
gunicorn app:app --timeout 120
```
Or investigate slow requests in your application.
### Out of Memory
If containers are OOM-killed:
1. Reduce worker count
2. Use `--max-requests` to restart workers periodically
3. Increase container memory limits
```bash
gunicorn app:app --workers 2 --max-requests 1000 --max-requests-jitter 100
```
### Connection Reset
If you see connection resets, ensure:
1. Load balancer health checks match your `/health` endpoint
2. Graceful timeout is sufficient for in-flight requests
3. Keepalive settings match between Gunicorn and upstream proxy
## See Also
- [Deploy](../deploy.md) - General deployment patterns
- [Settings](../reference/settings.md) - All configuration options
---
### Content Guides Gunicornc (`docs/content/guides/gunicornc.md`)
---
title: Control Interface (gunicornc)
menu:
guides:
weight: 15
---
# Control Interface (gunicornc)
Gunicorn provides a control interface similar to [birdc](https://bird.network.cz/?get_doc&v=20&f=bird-3.html) for the BIRD routing daemon. This allows you to inspect and manage a running Gunicorn instance via a Unix socket.
## Overview
The control interface consists of two parts:
1. **Control Socket Server** - Runs in the arbiter process, accepts commands via Unix socket
2. **gunicornc CLI** - Interactive client that connects to the control socket
## Quick Start
### Start Gunicorn with Control Socket
By default, Gunicorn creates the control socket at `$XDG_RUNTIME_DIR/gunicorn.ctl`. If `XDG_RUNTIME_DIR` is unset or does not point to an existing directory, it falls back to `$HOME/.gunicorn/gunicorn.ctl`:
```bash
gunicorn -w 4 myapp:app
```
Or specify a custom path:
```bash
gunicorn --control-socket /tmp/myapp.ctl -w 4 myapp:app
```
### Connect with gunicornc
```bash
# Connect to default socket (./gunicorn.ctl)
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
```
## Interactive Mode
When run without the `-c` flag, gunicornc enters interactive mode with readline support:
```
$ gunicornc
Connected to gunicorn.ctl
Type 'help' for available commands, 'quit' to exit.
gunicorn> show workers
PID AGE BOOTED LAST_BEAT
----------------------------------------
12345 1 yes 0.2s ago
12346 2 yes 0.1s ago
12347 3 yes 0.3s ago
Total: 3 workers
gunicorn> worker add 2
{
"added": 2,
"previous": 3,
"total": 5
}
gunicorn> quit
```
## Commands
### Show Commands
| Command | Description |
|---------|-------------|
| `show all` | Overview of all processes (arbiter, web workers, dirty workers) |
| `show workers` | List HTTP workers with status |
| `show dirty` | List dirty workers and apps |
| `show config` | Show current effective configuration |
| `show stats` | Show server statistics |
| `show listeners` | Show bound sockets |
| `help` | Show available commands |
### Worker Management
| Command | Description |
|---------|-------------|
| `worker add [N]` | Spawn N workers (default 1) |
| `worker remove [N]` | Remove N workers (default 1) |
| `worker kill