FAQ¶
WSGI bits¶
How do I set SCRIPT_NAME?¶
By default SCRIPT_NAME is an empty string. Set it via an environment variable
or HTTP header. Because the header contains an underscore it is only accepted
from trusted forwarders listed in forwarded_allow_ips.
Note
If your application should appear under a subfolder, SCRIPT_NAME typically
starts with a single leading slash and no trailing slash.
Server stuff¶
How do I reload my application in Gunicorn?¶
Send HUP to the master process for a graceful reload:
kill -HUP masterpid
How might I test a proxy configuration?¶
Use Hey to confirm that your proxy buffers responses correctly for synchronous workers:
hey -n 10000 -c 100 http://127.0.0.1:5000/
That benchmark issues 10,000 requests with a concurrency of 100.
How can I name processes?¶
Install setproctitle to give
Gunicorn processes meaningful names in tools such as ps and top. This helps
when running multiple Gunicorn instances. See the
proc_name setting for details.
Why is there no HTTP keep-alive?¶
The default sync workers target Nginx, which uses HTTP/1.0 for upstream connections. If you need to serve unbuffered internet traffic directly, pick an async worker instead.
Worker processes¶
How do I know which type of worker to use?¶
Read the design guide for guidance on worker types.
What types of workers are available?¶
See the worker_class configuration reference.
How can I figure out the best number of worker processes?¶
Follow the recommendations for tuning the number of workers.
How can I change the number of workers dynamically?¶
Send TTIN or TTOU to the master process:
kill -TTIN $masterpid # increment workers
kill -TTOU $masterpid # decrement workers
Does Gunicorn suffer from the thundering herd problem?¶
Potentially, when many sleeping handlers wake simultaneously but only one takes the request. There is ongoing work to mitigate this (issue #792). Monitor load if you use large numbers of workers or threads.
Why don't I see logs in the console?¶
Gunicorn 19.0 disabled console logging by default. Use --log-file=- to stream
logs to stdout. Console logging returned in 19.2.
Kernel parameters¶
High-concurrency deployments may need kernel tuning. These Linux-oriented tips apply to any network service.
How can I increase the maximum number of file descriptors?¶
Raise the per-process limit (remember sockets count as files). Running sudo
ulimit is ineffective—switch to root, adjust the limit, then launch Gunicorn.
Consider managing limits via systemd service units or init scripts.
How can I increase the maximum socket backlog?¶
Increase the queue of pending connections:
sudo sysctl -w net.core.somaxconn="2048"
How can I disable the use of sendfile()?¶
Pass --no-sendfile or set the SENDFILE=0 environment variable.
Troubleshooting¶
Django reports ImproperlyConfigured¶
Asynchronous workers may break django.core.urlresolvers.reverse. Use
reverse_lazy instead.
How do I avoid blocking in os.fchmod?¶
Gunicorn's heartbeat touches temporary files. On disk-backed filesystems (for
example /tmp on some distributions) os.fchmod can block if I/O stalls or the
filesystem fills up. Mount a tmpfs and point --worker-tmp-dir to it.
Check whether /tmp is RAM-backed:
df /tmp
If not, create a new tmpfs mount:
sudo cp /etc/fstab /etc/fstab.orig
sudo mkdir /mem
echo 'tmpfs /mem tmpfs defaults,size=64m,mode=1777,noatime,comment=for-gunicorn 0 0' | sudo tee -a /etc/fstab
sudo mount /mem
Verify the result:
df /mem
Then start Gunicorn with --worker-tmp-dir /mem.
Why are workers silently killed?¶
If a worker vanishes without logs, check for SIGKILL. Reverse proxies may show
502 responses while Gunicorn logs only new worker startups (for example,
[INFO] Booting worker). A common culprit is the OOM killer in cgroups-limited
environments.
Inspect kernel logs:
dmesg | grep gunicorn
If you see messages similar to Memory cgroup out of memory ... Killed process
(gunicorn.md), raise memory limits or adjust OOM behaviour.