Server Model

Gunicorn is based on the pre-fork worker model. This means that there is a central master process that manages a set of worker processes. The master never knows anything about individual clients. All requests and responses are handled completely by worker processes.

Master

The master process is a simple loop that listens for various process signals and reacts accordingly. It manages the list of running workers by listening for signals like TTIN, TTOU, and CHLD. TTIN and TTOU tell the master to increase or decrease the number of running workers. CHLD indicates that a child process has terminated, in this case the master process automatically restarts the failed worker.

Sync Workers

The most basic and the default worker type is a synchronous worker class that handles a single request at a time. This model is the simplest to reason about as any errors will affect at most a single request. Though as we describe below only processing a single request at a time requires some assumptions about how applications are programmed.

sync worker does not support persistent connections - each connection is closed after response has been sent (even if you manually add Keep-Alive or Connection: keep-alive header in your application).

Async Workers

The asynchronous workers available are based on Greenlets (via Eventlet and Gevent). Greenlets are an implementation of cooperative multi-threading for Python. In general, an application should be able to make use of these worker classes with no changes.

Tornado Workers

There’s also a Tornado worker class. It can be used to write applications using the Tornado framework. Although the Tornado workers are capable of serving a WSGI application, this is not a recommended configuration.

AsyncIO Workers

These workers are compatible with python3. You have two kind of workers.

The worker gthread is a threaded worker. It accepts connections in the main loop, accepted connections are added to the thread pool as a connection job. On keepalive connections are put back in the loop waiting for an event. If no event happen after the keep alive timeout, the connection is closed.

The worker gaiohttp is a full asyncio worker using aiohttp.

Note

The gaiohttp worker requires the aiohttp module to be installed. aiohttp has removed its native WSGI application support in version 2. If you want to continue to use the gaiohttp worker with your WSGI application (e.g. an application that uses Flask or Django), there are three options available:

1. Install aiohttp version 1.3.5 instead of version 2:

   $ pip install aiohttp==1.3.5

2. Use aiohttp_wsgi to wrap your WSGI application. You can take a look at the example in the Gunicorn repository.

3. Port your application to use aiohttp’s web.Application API.

4. Use the aiohttp.worker.GunicornWebWorker worker instead of the deprecated gaiohttp worker.