Gunicorn cheatsheet
Running Gunicorn
| Command | Description |
|---|---|
gunicorn myapp.wsgi:application | Start with default bind :8000 |
gunicorn -w 4 -b 127.0.0.1:8000 app:app | 4 workers on localhost:8000 |
gunicorn -c gunicorn.conf.py myapp.wsgi:application | Load settings from config file |
gunicorn --bind unix:/run/gunicorn.sock ... | Listen on Unix socket |
gunicorn --chdir /opt/myapp ... | Set working directory |
Service control (systemd)
| Command | Description |
|---|---|
systemctl status gunicorn | Service status |
systemctl restart gunicorn | Restart all workers |
systemctl reload gunicorn | Graceful reload (if unit supports HUP) |
journalctl -u gunicorn -f | Follow service logs |
kill -HUP $(cat /run/gunicorn.pid) | Graceful worker restart |
Inspection
| Command | Description |
|---|---|
ss -tlnp | grep gunicorn | TCP listeners |
ps aux | grep gunicorn | Master and worker processes |
curl -v http://127.0.0.1:8000/ | Test app directly (bypass proxy) |
ls -la /run/gunicorn.sock | Unix socket permissions |
Example gunicorn.conf.py
bind = "127.0.0.1:8000"
workers = 3
worker_class = "sync"
timeout = 30
max_requests = 1000
max_requests_jitter = 50
accesslog = "-"
errorlog = "-"
capture_output = True
Example systemd unit
[Service]
User=deploy
Group=deploy
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/venv/bin/gunicorn \
--config /opt/myapp/gunicorn.conf.py \
myproject.wsgi:application
Restart=on-failure
nginx proxy to Gunicorn (Unix socket)
location / {
proxy_pass http://unix:/run/gunicorn.sock;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
Pro tips
- Test the WSGI app import manually:
python -c "from myapp.wsgi import application" - Bind to
127.0.0.1or a socket — don't expose Gunicorn directly to the internet - Use
max_requeststo mitigate slow memory growth in long-lived workers - 502 from nginx usually means Gunicorn is down or the socket path is wrong
Practice scenarios
Hands-on Gunicorn scenarios on live Linux VMs: gunicorn