Gunicorn Worker Types

Gunicorn Worker Types

Gunicorn is a simple yet powerful python WSGI HTTP server, it supports some python frameworks natively. It has many features like server hooks, SSL support, multiple worker types, and integeration with Django and Paster.

Gunicorn is a pre-fork model server, which means that a master process is started and then a several worker processes are forked from the master. The worker processes are responsible for handling requests and returning a response to the client.

Gunicorn Support multiple worker types:

  • Sync Workers
  • Async Workers
  • Tornado Workers
  • AsyncIO workers

Each type provide certain functionality with handling the requests, worker-class configuration option is used to change the worker type that Gunicorn is using, the value of worker-class can be one of the following: sync, gevent, eventlet, tornado, gaiohttp, and gthread, the default worker type is sync.

Sync Workers

synchronous worker is the default type of Gunicorn, it represent the basic worker model. In this model each worker will handle one and only one request at a time, its more like the prefork mpm model in Apache webserver.

This type of worker is used with application that doesn’t  need long disk I/O or external requests, these types of request will make the other requests wait for the current one to finish, which will make them fail due to connection timeouts.


Async Workers

Asynchronous workers consists of two types: Gevent, and Eventlet, both are python libraries based on the Greenlet library which implements the coroutines in python. Coroutines provide some kind of concurrency inside the code, it can stop executing at one point and switch to another coroutine and return back when it finished.

Both Gevent and Eventlet are based on the Greenlet library and provide concurrency to network related tasks, for more information about gevent read gevent For the Working Python Developer. Gunicorn uses either one of the Async libraries to be able to handle more than one request and not be bounded to that request until its finished, this solves the earlier problem with sync worker.

One more thing to know, gevent and eventlet both use green threads, in python green threads implements threading on the program level instead of implementing threads on the OS level. Threading on the program level will be considered a blocking program so it needs to use asynchronous I/O operations to overcome this problem.

In general, no changes will be applied to the application in order for Async workers to function optimally.


Tornado Workers

Tornado workers are designed to work with the Tornado python framework. Tornado is a python framework and network library which provides async I/O non-blocking design model, which is ideal for handling long requests. Tornado workers are also capable of handling normal WSGI application but it is not recommended.


AsyncIO Workers

AsyncIO consists of two types: gthread and gaiohttp. gaiohttp uses aiohttp library which implements both client and server side of asynchronous I/O networking, it supports web sockets out of the box.

gthread is a full threaded worker and according to the official documentation gthread worker keeps the connection in a thread pool waiting for an event to happen to be handled by one of the threads.



Using one of the worker types will depend mainly on the type of the application, whether its CPU bounded or external I/O bounded, sync worker is the default for gunicorn, and it used with the applications that uses all its defined time to run the application without making external I/O requests, on other hand async workers will handle the long requests.