Quickstart for Python/WSGI applications

This quickstart will show you how to deploy simple WSGI applications and common web frameworks.

Python here is meant as CPython, for PyPy you need to use the specific plugin: The PyPy plugin, Jython support is on work.


You need at least uWSGI 1.4 to follow the quickstart. Anything older is no more maintained and is highly buggy!

Installing uWSGI with Python support


When you start learning uWSGI, try to build from official sources: using distro-supplied packages may bring you a lot of headaches. When things are clear, you can use modular builds (like the ones available in your distro).

uWSGI is a (big) C application, so you need a C compiler (like the gcc or clang) and Python development headers.

On a Debian-based distro an

apt-get install build-essential python-dev

will be enough.

You have various ways to install uWSGI for Python:

  • via pip

    pip install uwsgi
  • using the network installer

    curl http://uwsgi.it/install | bash -s default /tmp/uwsgi

    (this will install the uWSGI binary into /tmp/uwsgi, feel free to change it).

  • via downloading a source tarball and “making” it

    wget http://projects.unbit.it/downloads/uwsgi-latest.tar.gz
    tar zxvf uwsgi-latest.tar.gz
    cd <dir>

    (after the build you will have a uwsgi binary in the current directory).

Installing via your package distribution is not covered (would be impossibile to make everyone happy), but all of the general rules apply.

One thing you may want to take into account when testing this quickstart with distro-supplied packages, is that very probably your distribution has built uWSGI in modular way (every feature is a different plugin that must be loaded). To complete this quickstart, you have to prepend --plugin python,http to the first series of examples, and --plugin python when the HTTP router is removed (it could make no sense for you, just continue reading).

The first WSGI application

Let’s start with a simple “Hello World” example (this is for Python 2.x, Python 3.x requires the returned string to be bytes, see lower):

def application(env, start_response):
    start_response('200 OK', [('Content-Type','text/html')])
    return ["Hello World"]

(save it as foobar.py).

As you can see, it is composed of a single Python function. It is called “application” as this is default function that the uWSGI Python loader will search for (but you can obviously customize it).

The Python 3.x version is the following:

def application(env, start_response):
    start_response('200 OK', [('Content-Type','text/html')])
    return [b"Hello World"]

Deploy it on HTTP port 9090

Now start uWSGI to run an HTTP server/router passing requests to your WSGI application:

uwsgi --http :9090 --wsgi-file foobar.py

That’s all.

Adding concurrency and monitoring

The first tuning you would like to make is adding concurrency (by default uWSGI starts with a single process and a single thread).

You can add more processes with the --processes option or more threads with the --threads options (or you can have both).

uwsgi --http :9090 --wsgi-file foobar.py --master --processes 4 --threads 2

This will spawn 4 processes (each with 2 threads), a master process (will respawn your processes when they die) and the HTTP router (seen before).

One important task is monitoring. Understanding what is going on is vital in production deployment. The stats subsystem allows you to export uWSGI’s internal statistics as JSON:

uwsgi --http :9090 --wsgi-file foobar.py --master --processes 4 --threads 2 --stats

Make some request to your app and then telnet to the port 9191, you’ll get a lot of funny information. You may want to use “uwsgitop” (just pip install it), which is a top-like tool for monitoring instances.


Bind the stats socket to a private address (unless you know what you are doing), otherwise everyone could access it!

Putting behind a full webserver

Even though uWSGI HTTP router is solid and high-performance, you may want to put your application behind a fully-capable webserver.

uWSGI natively speaks HTTP, FastCGI, SCGI and its specific protocol named “uwsgi” (yes, wrong naming choice). The best performing protocol is obviously uwsgi, already supported by nginx and Cherokee (while various Apache modules are available).

A common nginx config is the following:

location / {
    include uwsgi_params;

This means “pass every request to the server bound to port 3031 speaking the uwsgi protocol”.

Now we can spawn uWSGI to natively speak the uwsgi protocol:

uwsgi --socket --wsgi-file foobar.py --master --processes 4 --threads 2 --stats

If you’ll run ps aux, you will see one process less. The HTTP router has been removed as our “workers” (the processes assigned to uWSGI) natively speak the uwsgi protocol.

Automatically starting uWSGI on boot

If you think about writing some init.d script for spawning uWSGI, just sit (and calm) down and check if your system offers you a better (more modern) approach.

Each distribution has chosen its startup system (Upstart, SystemD, etc.) and there are tons of process managers available: Supervisor, god, Circus, etc.

uWSGI will integrate very well with all of them (we hope), but if you plan to deploy a big number of apps check the uWSGI Emperor, it is the dream of every devops.

Deploying Django

Django is very probably the most used Python web framework around. Deploying it is pretty easy (we continue our configuration with 4 processes with 2 threads each).

We suppose the Django project is in /home/foobar/myproject:

uwsgi --socket --chdir /home/foobar/myproject/ --wsgi-file myproject/wsgi.py --master --processes 4 --threads 2 --stats

(with --chdir we move to a specific directory). In Django this is required to correctly load modules.

If the file /home/foobar/myproject/myproject/wsgi.py (or whatever you have called your project) does not exist, you are very probably using an old (< 1.4) version of Django. In such a case you need a little bit more configuration:

uwsgi --socket --chdir /home/foobar/myproject/ --pythonpath .. --env DJANGO_SETTINGS_MODULE=myproject.settings --module "django.core.handlers.wsgi:WSGIHandler()" --processes 4 --threads 2 --stats

ARGH! What the hell is this?! Yes, you are right, dealing with such long command lines is basically unpractical (and foolish). uWSGI supports various configuration styles. In this quickstart we will use .ini files.

socket =
chdir = /home/foobar/myproject/
pythonpath = ..
env = DJANGO_SETTINGS_MODULE=myproject.settings
module = django.core.handlers.wsgi:WSGIHandler()
processes = 4
threads = 2
stats =

A lot better!

Just run it:

uwsgi yourfile.ini

Older (< 1.4) Django releases need to set env, module and the pythonpath (.. allow us to reach the myproject.settings module).

Deploying Flask

Flask is popular Python web microframework.

Save the following example as myflaskapp.py:

from flask import Flask

app = Flask(__name__)

def index():
    return "<span style='color:red'>I am app 1</span>"

Flask exports its WSGI function (the one we called “application” at the beginning of this quickstart) as “app”, so we need to instruct uWSGI to use it. We still continue to use the 4 processes/2 threads and the uwsgi socket as the base:

uwsgi --socket --wsgi-file myflaskapp.py --callable app --processes 4 --threads 2 --stats

(the only addition is the --callable option).

Deploying web2py

Again a popular choice. Unzip the web2py source distribution on a directory of choice and write a uWSGI config file:

http = :9090
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8


On recent web2py releases you may need to copy the wsgihandler.py script out of the handlers directory.

We used the HTTP router again. Just go to port 9090 with your browser and you will see the web2py welcome page.

Click on the administrative interface and... oops, it does not work as it requires HTTPS. Do not worry, the uWSGI router is HTTPS-capable (be sure you have OpenSSL development headers: install them and rebuild uWSGI, the build system will automatically detect it).

First of all generate your key and certificate:

openssl genrsa -out foobar.key 2048
openssl req -new -key foobar.key -out foobar.csr
openssl x509 -req -days 365 -in foobar.csr -signkey foobar.key -out foobar.crt

Now you have 2 files (well 3, counting the foobar.csr), foobar.key and foobar.crt. Change the uWSGI config:

https = :9090,foobar.crt,foobar.key
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

Re-run uWSGI and connect to port 9090 using https:// with your browser.

A note on Python threads

If you start uWSGI without threads, the Python GIL will not be enabled, so threads generated by your application will never run. You may not like that choice, but remember that uWSGI is a language-independent server, so most of its choices are for maintaining it “agnostic”.

But do not worry, there are basically no choices made by the uWSGI developers that cannot be changed with an option.

If you want to maintain Python threads support without starting multiple threads for your application, just add the --enable-threads option (or enable-threads = true in ini style).


uWSGI can be configured to search for Python modules in a specific virtualenv.

Just add virtualenv = <path> to your options.

Security and availability

Always avoid running your uWSGI instances as root. You can drop privileges using the uid and gid options:

https = :9090,foobar.crt,foobar.key
uid = foo
gid = bar
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

If you need to bind to privileged ports (like 443 for HTTPS), use shared sockets. They are created before dropping privileges and can be referenced with the =N syntax, where N is the socket number (starting from 0):

shared-socket = :443
https = =0,foobar.crt,foobar.key
uid = foo
gid = bar
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8

A common problem with webapp deployment is “stuck requests”. All of your threads/workers are stuck (blocked on request) and your app cannot accept more requests. To avoid that problem you can set a harakiri timer. It is a monitor (managed by the master process) that will destroy processes stuck for more than the specified number of seconds (choose harakiri value carefully). For example, you may want to destroy workers blocked for more than 30 seconds:

shared-socket = :443
https = =0,foobar.crt,foobar.key
uid = foo
gid = bar
chdir = path_to_web2py
module = wsgihandler
master = true
processes = 8
harakiri = 30

In addition to this, since uWSGI 1.9, the stats server exports the whole set of request variables, so you can see (in realtime) what your instance is doing (for each worker, thread or async core).


The uWSGI offloading subsystem allows you to free your workers as soon as possible when some specific pattern matches and can be delegated to a pure-C thread (sending static file from the filesystem, transferring data from the network to the client and so on).

Offloading is very complex, but its use is transparent to the end user. If you want to try, just add --offload-threads <n>, where <n> is the number of threads to spawn (one per CPU is a good value).

When offload threads are enabled, all of the parts that can be optimized will be automatically detected.

And now

You should already be able to go in production with such few concepts, but uWSGI is an enormous project with hundreds of features and configurations. If you want to be a better sysadmin, continue reading the full docs.