Worker Processes

workers

  • -w INT, --workers INT
  • 1

The number of worker processes for handling requests.

A positive integer generally in the 2-4 x $(NUM_CORES) range. You’ll want to vary this a bit to find the best for your particular application’s work load.

By default, the value of the WEB_CONCURRENCY environment variable. If it is not defined, the default is 1.

worker_class

  • -k STRING, --worker-class STRING
  • sync

The type of workers to use.

The default class (sync) should handle most “normal” types of workloads. You’ll want to read Design for information on when you might want to choose one of the other worker classes. Required libraries may be installed using setuptools’ extras_require feature.

A string referring to one of the following bundled classes:

  • sync
  • eventlet - Requires eventlet >= 0.24.1 (or install it via pip install gunicorn[eventlet])
  • gevent - Requires gevent >= 1.4 (or install it via pip install gunicorn[gevent])
  • tornado - Requires tornado >= 0.2 (or install it via pip install gunicorn[tornado])
  • gthread - Python 2 requires the futures package to be installed (or install it via pip install gunicorn[gthread])

Optionally, you can provide your own worker by giving Gunicorn a Python path to a subclass of gunicorn.workers.base.Worker. This alternative syntax will load the gevent class: gunicorn.workers.ggevent.GeventWorker.

threads

  • --threads INT
  • 1

The number of worker threads for handling requests.

Run each worker with the specified number of threads.

A positive integer generally in the 2-4 x $(NUM_CORES) range. You’ll want to vary this a bit to find the best for your particular application’s work load.

If it is not defined, the default is 1.

This setting only affects the Gthread worker type.

Note

If you try to use the sync worker type and set the threads setting to more than 1, the gthread worker type will be used instead.

worker_connections

  • --worker-connections INT
  • 1000

The maximum number of simultaneous clients.

This setting only affects the Eventlet and Gevent worker types.

max_requests

  • --max-requests INT
  • 0

The maximum number of requests a worker will process before restarting.

Any value greater than zero will limit the number of requests a worker will process before automatically restarting. This is a simple method to help limit the damage of memory leaks.

If this is set to zero (the default) then the automatic worker restarts are disabled.

max_requests_jitter

  • --max-requests-jitter INT
  • 0

The maximum jitter to add to the max_requests setting.

The jitter causes the restart per worker to be randomized by randint(0, max_requests_jitter). This is intended to stagger worker restarts to avoid all workers restarting at the same time.

New in version 19.2.

timeout

  • -t INT, --timeout INT
  • 30

Workers silent for more than this many seconds are killed and restarted.

Generally set to thirty seconds. Only set this noticeably higher if you’re sure of the repercussions for sync workers. For the non sync workers it just means that the worker process is still communicating and is not tied to the length of time required to handle a single request.

graceful_timeout

  • --graceful-timeout INT
  • 30

Timeout for graceful workers restart.

After receiving a restart signal, workers have this much time to finish serving requests. Workers still alive after the timeout (starting from the receipt of the restart signal) are force killed.

keepalive

  • --keep-alive INT
  • 2

The number of seconds to wait for requests on a Keep-Alive connection.

Generally set in the 1-5 seconds range for servers with direct connection to the client (e.g. when you don’t have separate load balancer). When Gunicorn is deployed behind a load balancer, it often makes sense to set this to a higher value.

Note

sync worker does not support persistent connections and will ignore this option.