Common uWSGI configuration

uWSGI seemingly can do a bit of everything, but covering that is a job for the uWSGI documentation. This page covers some basic configuration tasks that may be required just to get your application running, and other tricks you should consider.

Starting within a particular directory

If your Python application needs to start within a particular directory, use the uWSGI --chdir /starting/path command-line option or chdir = /starting/path in your .ini file.


If your Python application needs to run within a virtualenv, and you didn't already activate that virtualenv to run uWSGI itself, point to the virtualenv with the uWSGI -H command-line option or with virtualenv = /path/to/virtualenv in your .ini file.

Environment variables

uWSGI command-line invocation: --env varname=value

.ini file: env varname=value

Request timeout

If the application hangs while processing a request, you can configure uWSGI to destroy the application process handling the request after a timeout using the -t seconds command-line option or harakiri = seconds in your .ini file.

Some uWSGI configuration examples show this timeout specified without any advice. Consider the following before setting it:

  • For your particular application, it may leave data in a bad state which requires manual intervention to resolve.
  • The timeout is not specific to particular types of requests, so it has to be large enough for the most lengthy request that your application ever handles, under non-ideal conditions.
  • It has to be low enough to take effect before a user will take action themselves, possibly exacerbating the underlying situation.
  • The application may not actually be hung — it may be generating output to the client, but still get zapped if the request isn't completely finished within the configured number of seconds.

I don't think that processing is helpful for many applications. Refer to the uWSGI FAQ entry on Harakiri mode for more information.


uWSGI can provide statistics in JSON format over a socket, and provides a tool called uwsgitop to maintain a display of activity.

Add stats = to your .ini file, then access the stats as follows using netcat or uwsgitop:

$ nc 9191
$ uwsgitop
uwsgi-2.0.5 - Sun May 18 16:00:49 2014 - req: 778571 - RPS: 5291 - lq: 0 - tx: 51.0G
node: trawick-ip - cwd: /home/trawick/myhg/projects/pyweb/app/wsgi - uid: 1 - gid: 1 - masterpid: 14760
 WID    %       PID     REQ     RPS     EXC     SIG     STATUS  AVG     RSS     VSZ     TX      RunT    
 1      14.0    14766   108708  753     0       0       idle    0ms     0       0       7.0G    22275
 2      16.0    14767   124356  868     0       0       idle    0ms     0       0       8.0G    25575
 4      30.4    14769   236788  1596    0       0       busy    0ms     0       0       15.0G   49106
 3      39.7    14768   308719  2074    0       0       busy    0ms     0       0       20.0G   64232