How to use Django with uWSGI¶
uWSGI is a fast, self-healing and developer/sysadmin-friendly application container server coded in pure C.
See also
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.
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:
# Install current stable version.
$ python -m pip install uwsgi
# Or install LTS (long term support).
$ python -m pip install https://projects.unbit.it/downloads/uwsgi-lts.tar.gz
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.
Configuring and starting the uWSGI server for Django¶
uWSGI supports multiple ways to configure the process. See uWSGI’s configuration documentation.
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/project-master.pid \
--socket=127.0.0.1:49152 \ # 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 virtual environment
--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 mysite/wsgi.py
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 How to deploy with WSGI 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 themysite
package.module
: The WSGI module to use – probably themysite.wsgi
module thatstartproject
creates.env
: Should probably contain at leastDJANGO_SETTINGS_MODULE
.home
: Optional path to your project virtual environment.
Example ini configuration file:
[uwsgi]
chdir=/path/to/your/project
module=mysite.wsgi:application
master=True
pidfile=/tmp/project-master.pid
vacuum=True
max-requests=5000
daemonize=/var/log/uwsgi/yourproject.log
Example ini configuration file usage:
uwsgi --ini uwsgi.ini
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 Files section of the Unicode reference guide for details.
See the uWSGI docs on managing the uWSGI process for information on starting, stopping and reloading the uWSGI workers.