Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
126 lines (90 sloc) 4.79 KB
How to use Django with uWSGI
.. highlight:: bash
uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application
container server coded in pure C.
.. _uWSGI:
.. seealso::
The uWSGI docs offer a `tutorial`_ covering Django, nginx, and uWSGI (one
possible deployment setup of many). The docs below are focused on how to
integrate Django with uWSGI.
.. _tutorial:
Prerequisite: uWSGI
The uWSGI wiki describes several `installation procedures`_. Using pip, the
Python package manager, you can install any uWSGI version with a single
command. For example:
.. code-block:: console
# Install current stable version.
$ pip install uwsgi
# Or install LTS (long term support).
$ pip install
.. _installation procedures:
.. warning::
Some distributions, including Debian and Ubuntu, ship an outdated version
of uWSGI that does not conform to the WSGI specification. Versions prior to
1.2.6 do not call ``close`` on the response object after handling a
request. In those cases the :data:`~django.core.signals.request_finished`
signal isn't sent. This can result in idle connections to database and
memcache servers.
uWSGI model
uWSGI operates on a client-server model. Your Web server (e.g., nginx, Apache)
communicates with a django-uwsgi "worker" process to serve dynamic content.
See uWSGI's `background documentation`_ for more detail.
.. _background documentation:
Configuring and starting the uWSGI server for Django
uWSGI supports multiple ways to configure the process. See uWSGI's
`configuration documentation`_ and `examples`_.
.. _configuration documentation:
.. _examples:
Here's an example command to start a uWSGI server::
uwsgi --chdir=/path/to/your/project \
--module=mysite.wsgi:application \
--env DJANGO_SETTINGS_MODULE=mysite.settings \
--master --pidfile=/tmp/ \
--socket= \ # can also be a file
--processes=5 \ # number of worker processes
--uid=1000 --gid=2000 \ # if root, uwsgi can drop privileges
--harakiri=20 \ # respawn processes taking more than 20 seconds
--max-requests=5000 \ # respawn processes after serving 5000 requests
--vacuum \ # clear environment on exit
--home=/path/to/virtual/env \ # optional path to a virtualenv
--daemonize=/var/log/uwsgi/yourproject.log # background the process
This assumes you have a top-level project package named ``mysite``, and
within it a module :file:`mysite/` that contains a WSGI ``application``
object. This is the layout you'll have if you ran ``django-admin
startproject mysite`` (using your own project name in place of ``mysite``) with
a recent version of Django. If this file doesn't exist, you'll need to create
it. See the :doc:`/howto/deployment/wsgi/index` documentation for the default
contents you should put in this file and what else you can add to it.
The Django-specific options here are:
* ``chdir``: The path to the directory that needs to be on Python's import
path -- i.e., the directory containing the ``mysite`` package.
* ``module``: The WSGI module to use -- probably the ``mysite.wsgi`` module
that :djadmin:`startproject` creates.
* ``env``: Should probably contain at least ``DJANGO_SETTINGS_MODULE``.
* ``home``: Optional path to your project virtualenv.
Example ini configuration file::
Example ini configuration file usage::
uwsgi --ini uwsgi.ini
.. admonition:: Fixing ``UnicodeEncodeError`` for file uploads
If you get a ``UnicodeEncodeError`` when uploading files with file names
that contain non-ASCII characters, make sure uWSGI is configured to accept
non-ASCII file names by adding this to your ``uwsgi.ini``::
env = LANG='en_US.UTF-8'
See the :ref:`unicode-files` section of the Unicode reference guide for
See the uWSGI docs on `managing the uWSGI process`_ for information on
starting, stopping and reloading the uWSGI workers.
.. _managing the uWSGI process:
Jump to Line
Something went wrong with that request. Please try again.