gunicorn python

gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX, fast clients and sleepy applications.


Gunicorn ‘Green Unicorn’ is a Python WSGI HTTP Server for UNIX. It’s a pre-fork worker model ported from Ruby’s Unicorn_ project. The Gunicorn server is broadly compatible with various web frameworks, simply implemented, light on server resource usage, and fairly speedy.

Feel free to join us in #gunicorn_ on freenode_.


Gunicorn requires Python 2.x >= 2.5. Python 3.x support is planned.

Install from sources::

$ python install

Or from Pypi::

$ easy_install -U gunicorn

You may also want to install Eventlet_ or Gevent_ if you expect that your application code may need to pause for extended periods of time during request processing. Check out the FAQ_ for more information on when you’ll want to consider one of the alternate worker types.

To install eventlet::

$ easy_install -U eventlet

If you encounter errors when compiling the extensions for Eventlet_ or Gevent_ you most likely need to install a newer version of libev_ or libevent_.

Basic Usage

After installing Gunicorn you will have access to three command line scripts that can be used for serving the various supported web frameworks: gunicorn, gunicorn_django, and gunicorn_paster.

Commonly Used Arguments +++++++++++++++++++++++

  • -c CONFIG, --config=CONFIG - Specify the path to a config file_

  • -b BIND, --bind=BIND - Specify a server socket to bind. Server sockets can be any of $(HOST), $(HOST):$(PORT), or unix:$(PATH). An IP is a valid $(HOST).

  • -w WORKERS, --workers=WORKERS - The number of worker processes. This number should generally be between 2-4 workers per core in the server. Check the FAQ_ for ideas on tuning this parameter.

  • -k WORKERCLASS, --worker-class=WORKERCLASS - The type of worker process to run. You’ll definitely want to read the production page_ for the implications of this parameter. You can set this to egg:gunicorn#$(NAME) where $(NAME) is one of sync, eventlet, gevent, or tornado. sync is the default.

  • -n APP_NAME, --name=APP_NAME - If setproctitle_ is installed you can adjust the name of Gunicorn process as they appear in the process system table (which affects tools like ps and top).

    sync=gunicorn.workers.sync:SyncWorker eventlet=gunicorn.workers.geventlet:EventletWorker gevent=gunicorn.workers.ggevent:GeventWorker tornado

There are various other parameters that affect user privileges, logging, etc. You can see the complete list with the expected::

$ gunicorn -h

gunicorn ++++++++

The first and most basic script is used to server ‘bare’ WSGI applications that don’t require a translation layer. Basic usage::


Where APP_MODULE is of the pattern $(MODULE_NAME):$(VARIABLE_NAME). The module name can be a full dotted path. The variable name refers to a WSGI callable that should be found in the specified module.

Example with test app::

$ cd examples
$ gunicorn --workers=2 test:app

gunicorn_django +++++++++++++++

You might not have guessed it, but this script is used to server Django applications. Basic usage::

$ gunicorn_django [OPTIONS] [SETTINGS_PATH]

By default SETTINGS_PATH will look for in the current directory.

Example with your Django project::

$ cd path/to/yourdjangoproject
$ gunicorn_django --workers=2

Alternatively, you can install some Gunicorn magic directly into your Django project and use the provided command for running the server.

First you’ll need to add gunicorn to your INSTALLED_APPS in the settings file::


Then you can run::

python run_gunicorn

gunicorn_paster +++++++++++++++

Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, …). We apologize for the lack of script name creativity. And some usage::

$ gunicorn_paster [OPTIONS] paste_config.ini

Simple example::

$ cd yourpasteproject
$ gunicorn_paste --workers=2 development.ini

If you’re wanting to keep on keeping on with the usual paster serve command, you can specify the Gunicorn server settings in your configuration file::

use = egg:gunicorn#main
host =
port = 5000

And then as per usual::

$ cd yourpasteproject
$ paster serve development.ini workers=2


Gunicorn is released under the MIT License. See the LICENSE_ file for more details.

.. _Unicorn: .. _#gunicorn: .. _freenode: .. _Eventlet: .. _Gevent: .. _FAQ: .. _libev: .. _libevent: .. _production page: .. _config file: .. _setproctitle: .. _LICENSE:

Related Repositories



gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX, fast clients and sleepy applications. ...



This is a bare Django project that includes a Fabric file, commonly known as a fabfile, to setup an Ubuntu 11.10 server with Django, Nginx, gunicorn and upstart. ...



A curses application for managing gunicorn processes. ...



An experimental docker setup for Python / Gunicorn / Nginx stack ...



simple gunicorn remote control with fabric ...

Top Contributors

benoitc davisp jbergstroem ericflo tilgovi tmc anandology brtsz bencochran geo-kollias jezdez lemonad olt paparent paulsmith thomasst tswicegood


-   0.11.2 zip tar
-   0.11.1 zip tar
-   0.11.0 zip tar
-   0.10.1 zip tar
-   0.10.0 zip tar
-   0.10.0-py24 zip tar
-   0.10.0-dev zip tar
-   0.9.1 zip tar
-   0.9.0 zip tar
-   0.9 zip tar
-   0.8.2 zip tar
-   0.8.0 zip tar
-   0.7.2 zip tar
-   0.7.1 zip tar
-   0.7.0 zip tar
-   0.7 zip tar
-   0.6.7 zip tar
-   0.6.6 zip tar
-   0.6.4 zip tar
-   0.6.3 zip tar
-   0.6.2 zip tar
-   0.6.1 zip tar
-   0.6 zip tar
-   0.5.1 zip tar
-   0.5 zip tar
-   0.4.2 zip tar
-   0.4.1 zip tar
-   0.4 zip tar
-   0.3.2 zip tar
-   0.3.1 zip tar