How to use Django with Gunicorn

Gunicorn (‘Green Unicorn’) is a pure-Python WSGI server for UNIX. It has no dependencies and is easy to install and use.

There are two ways to use Gunicorn with Django. One is to have Gunicorn treat Django as just another WSGI application. The second is to use Gunicorn’s special integration with Django.

Installing Gunicorn

Installing gunicorn is as easy as sudo pip install gunicorn. For more details, see the gunicorn documentation.

Running Django in Gunicorn as a generic WSGI application

When Gunicorn is installed, a gunicorn command is available which starts the Gunicorn server process. At its simplest, gunicorn just needs to be called with a the location of a WSGI application object.:

gunicorn [OPTIONS] APP_MODULE

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

So for a typical Django project, invoking gunicorn would look like:

gunicorn myproject.wsgi:application

(This requires that your project be on the Python path; the simplest way to ensure that is to run this command from the same directory as your manage.py file.)

Using Gunicorn’s Django integration

To use Gunicorn’s built-in Django integration, first add "gunicorn" to INSTALLED_APPS. Then run python manage.py run_gunicorn.

This provides a few Django-specific niceties:

  • sets the gunicorn process name to be that of the project
  • validates installed models
  • allows an --adminmedia option for passing in the location of the admin media files, mimicing the behavior of runserver.

See Gunicorn’s deployment documentation for additional tips on starting and maintaining the Gunicorn server.

« previous | up | next »