We strongly recommend running Gunicorn behind a proxy server.
Although many HTTP proxies exist, we recommend Nginx. When using the default synchronous workers you must ensure the proxy buffers slow clients; otherwise Gunicorn becomes vulnerable to denial-of-service attacks. Use Hey to verify proxy behaviour.
An example configuration for fast clients with Nginx (source):
To support streaming requests/responses or patterns such as Comet, long polling, or WebSockets, disable proxy buffering and run Gunicorn with an async worker class:
To ignore aborted requests (for example, health checks that close connections prematurely) enable proxy_ignore_client_abort:
The default value for proxy_ignore_client_abort is off. If it remains off Nginx logs will report error 499 and Gunicorn may log Ignoring EPIPE when the log level is debug.
Pass protocol information to Gunicorn so applications can generate correct URLs. Add this header to your location block:
If Nginx runs on a different host, tell Gunicorn which proxies are trusted so it accepts the X-Forwarded-* headers:
When all traffic comes from trusted proxies (for example Heroku) you can set --forwarded-allow-ips='*'. This is dangerous if untrusted clients can reach Gunicorn directly, because forged headers could make your application serve secure content over plain HTTP.
Gunicorn 19 changed the handling of REMOTE_ADDR to conform to RFC 3875, meaning it now records the proxy IP rather than the upstream client. To log the real client address, set access_log_format to include X-Forwarded-For:
When binding Gunicorn to a UNIX socket REMOTE_ADDR will be empty.
The PROXY protocol allows load balancers and reverse proxies to pass original client connection information (IP address, port) to backend servers. This is especially useful when TLS termination happens at the proxy layer.
Gunicorn supports both PROXY protocol v1 (text format) and v2 (binary format).
Enable PROXY protocol with the --proxy-protocol option:
Using --proxy-protocol without a value is equivalent to auto.
Only enable PROXY protocol when Gunicorn is behind a trusted proxy that sends PROXY headers. Configure --proxy-allow-from to restrict which IPs can send PROXY protocol headers.
HAProxy can send PROXY protocol headers to backends. Example configuration:
Start Gunicorn to accept PROXY protocol:
stunnel can terminate TLS and forward connections with PROXY protocol headers:
The protocol = proxy directive tells stunnel to prepend PROXY protocol v1 headers to forwarded connections.
AWS Network Load Balancers (NLB) and Application Load Balancers (ALB) support PROXY protocol v2. Enable it in the target group settings, then configure Gunicorn:
When using --proxy-allow-from '*' ensure Gunicorn is not directly accessible from the internet—only through the load balancer.
Install Gunicorn inside your project virtual environment to keep versions isolated:
Force installation into the active virtual environment with --ignore-installed:
Do not enable Gunicorn's daemon mode when using process monitors. These supervisors expect to manage the direct child process.
Use Gaffer with gafferd to manage Gunicorn:
Create a Procfile if you prefer:
Start Gunicorn via Gaffer:
Or load it into a running gafferd instance:
runit is a popular supervisor. A sample service script (see the full example):
Save as /
etc/sv/<app_name>/run, make it executable, and symlink into /
etc/service/<app_name>. runit will then supervise Gunicorn.
Supervisor configuration example (adapted from examples/supervisor.conf):
Sample Upstart config (logs go to /var/log/upstart/myapp.log):
systemd can create a UNIX socket and launch Gunicorn on demand.
Type=notify lets Gunicorn report readiness to systemd. If the service should run under a transient user consider adding DynamicUser=true. Tighten permissions further with ProtectSystem=strict if the app permits.
Socket activation file:
Enable and start the socket so it begins listening immediately and on reboot:
Test connectivity from the nginx user (Debian defaults to www-data):
Use systemctl show --value -p MainPID gunicorn.service to retrieve the main process ID or systemctl kill -s HUP gunicorn.service to send signals.
Configure Nginx to proxy to the new socket: