Signal Handling

A quick reference to the signals handled by Gunicorn. This includes the signals used internally to coordinate with worker processes.

Master process

• QUIT, INT — quick shutdown.
• TERM — graceful shutdown; waits for workers to finish requests up to graceful_timeout.
• HUP — reload configuration, spawn new workers, and gracefully stop old ones. If the app is not preloaded (see preload_app) the application code is reloaded too.
• TTIN — increase worker count by one.
• TTOU — decrease worker count by one.
• USR1 — reopen log files.
• USR2 — perform a binary upgrade. Send TERM to the old master afterwards to stop it. This also reloads preloaded applications (see binary upgrades).
• WINCH — gracefully stop workers when Gunicorn runs as a daemon.

Worker process

Workers rarely need direct signalling—if the master stays alive it will respawn workers automatically.

• QUIT, INT — quick shutdown.
• TERM — graceful shutdown.
• USR1 — reopen log files.

Reload the configuration

Use HUP to reload Gunicorn on the fly:

2013-06-29 06:26:55 [20682] [INFO] Handling signal: hup
2013-06-29 06:26:55 [20682] [INFO] Hang up: Master
2013-06-29 06:26:55 [20703] [INFO] Booting worker with pid: 20703
2013-06-29 06:26:55 [20702] [INFO] Booting worker with pid: 20702
2013-06-29 06:26:55 [20688] [INFO] Worker exiting (pid: 20688)
2013-06-29 06:26:55 [20687] [INFO] Worker exiting (pid: 20687)
2013-06-29 06:26:55 [20689] [INFO] Worker exiting (pid: 20689)
2013-06-29 06:26:55 [20704] [INFO] Booting worker with pid: 20704

Gunicorn reloads its settings, starts new workers, and gracefully shuts down the previous ones. If the app is not preloaded it reloads the application module as well.

Upgrading to a new binary on the fly

Changed in 19.6.0

PID files now follow the pattern <name>.pid.2 instead of <name>.pid.oldbin.

You can replace the Gunicorn binary without downtime. Incoming requests remain served and preloaded applications reload.

1. Replace the old binary and send USR2 to the master. Gunicorn starts a new master whose PID file ends with .2 and spawns new workers.

PID USER      PR  NI  VIRT  RES  SHR S  %CPU %MEM    TIME+  COMMAND
20844 benoitc   20   0 54808  11m 3352 S   0.0  0.1   0:00.36 gunicorn: master [test:app]
20849 benoitc   20   0 54808 9.9m 1500 S   0.0  0.1   0:00.02 gunicorn: worker [test:app]
20850 benoitc   20   0 54808 9.9m 1500 S   0.0  0.1   0:00.01 gunicorn: worker [test:app]
20851 benoitc   20   0 54808 9.9m 1500 S   0.0  0.1   0:00.01 gunicorn: worker [test:app]
20854 benoitc   20   0 55748  12m 3348 S   0.0  0.2   0:00.35 gunicorn: master [test:app]
20859 benoitc   20   0 55748  11m 1500 S   0.0  0.1   0:00.01 gunicorn: worker [test:app]
20860 benoitc   20   0 55748  11m 1500 S   0.0  0.1   0:00.00 gunicorn: worker [test:app]
20861 benoitc   20   0 55748  11m 1500 S   0.0  0.1   0:00.01 gunicorn: worker [test:app]

1. Send WINCH to the old master to gracefully stop its workers.

You can still roll back while the old master keeps its listen sockets:

1. Send HUP to the old master to restart its workers without reloading the config file.
2. Send TERM to the new master to shut down its workers gracefully.
3. Send QUIT to the new master to force it to exit.

If the new workers linger, send KILL after the new master quits.

To complete the upgrade, send TERM to the old master so only the new server continues running:

PID USER      PR  NI  VIRT  RES  SHR S  %CPU %MEM    TIME+  COMMAND
20854 benoitc   20   0 55748  12m 3348 S   0.0  0.2   0:00.45 gunicorn: master [test:app]
20859 benoitc   20   0 55748  11m 1500 S   0.0  0.1   0:00.02 gunicorn: worker [test:app]
20860 benoitc   20   0 55748  11m 1500 S   0.0  0.1   0:00.02 gunicorn: worker [test:app]
20861 benoitc   20   0 55748  11m 1500 S   0.0  0.1   0:00.01 gunicorn: worker [test:app]