uWSGI Documentation (for 0.9.4)
Command line usage
Usage: ./uwsgi [options...] -s|--socket <name> path (or name) of UNIX/TCP socket to bind to -l|--listen <num> set socket listen queue to <n> (default 64, maximum is system dependent) -z|--socket-timeout <sec> set socket timeout to <sec> seconds (default 4 seconds) -b|--buffer-size <n> set buffer size to <n> bytes -L|--disable-logging disable request logging (only errors or server messages will be logged) -x|--xmlconfig <path> path of xml config file (no ROCK_SOLID) -w|--module <module> name of python config module (no ROCK_SOLID) -t|--harakiri <sec> set harakiri timeout to <sec> seconds -p|--processes <n> spawn <n> uwsgi worker processes -O|--optimize <n> set python optimization level to <n> (no ROCK_SOLID) -v|--max-vars <n> set maximum number of vars/headers to <n> -A|--sharedarea <n> create a shared memory area of <n> pages -c|--cgi-mode set cgi mode (no ROCK_SOLID) -C|--chmod-socket chmod socket to 666 -P|--profiler enable profiler (no ROCK_SOLID) -m|--memory-report enable memory usage report (Linux/OSX only, no ROCK_SOLID) -i|--single-interpreter single interpreter mode (no ROCK_SOLID) -a|--abstract-socket set socket in the abstract namespace (Linux only) -T|--enable-threads enable threads support (no ROCK_SOLID) -M|--master enable master process manager -H|--home <path> set python home/virtualenv -h|--help this help -r|--reaper process reaper (call waitpid(-1,...) after each request) -R|--max-requests maximum number of requests for each worker -j|--test test if uWSGI can import a module -Q|--spooler <dir> run the spooler on directory <dir> --pidfile <file> write the masterpid to <file> --chroot <dir> chroot to directory <dir> (only root) --gid <id> setgid to <id> (only root) --uid <id> setuid to <id> (only root) --sync-log let uWSGI does its best to avoid logfile mess --no-server initialize the uWSGI server then exit. Useful for testing and using uwsgi embedded module --paste <config:/egg:> load applications using paste.deploy.loadapp() --pythonpath <dir> add <dir> to PYTHONPATH -d|--daemonize <logfile> daemonize and log into <logfile>
Hello world
Write a simple wsgi application:
def application(environ, start_response):
start_response('200 OK', [('Content-Type', 'text/plain')])
yield 'Hello World\n'
save it in your preferred directory (obviously with the .py extension, pippo_wsgi.py for example) then copy the uwsgi binary in the same dir (if you have not istalled it in the system path).
Now you have two main choice to configure uWSGI, via an xmlfile or using only python.
The xml way
write a simple xml configuration file to define your app (myconfig.xml):
<uwsgi>
<app mountpoint="/pippo">
<script>pippo_wsgi</script>
</app>
</uwsgi>
now launch the uwsgi server
./uwsgi -s /tmp/uwsgi.sock -C -x myconfig.xml *** Starting uWSGI on [XXXXXXXXXXXX] *** binding on UNIX socket: /tmp/uwsgi.sock chmod() socket to 666 for lazy and brave users parsing config file myconfig.xml interpreter for app 1 initialized. application 1 (/pippo) ready config file parsed. spawned uWSGI worker 0 (pid: XXXX)
If you have installed uWSGI from a package (as on OSX), you have it in the system path (in /usr/bin). The python engine, search modules in the current directory then in the configured python paths. To add a directory to the pythonpath use the <pythonpath> directive:
<uwsgi>
<pythonpath>/Users/serena/myapp</pythonpath>
<app mountpoint="/pippo">
<script>pippo_wsgi</script>
</app>
</uwsgi>
You can add upto 64 <pythonpath> directives.
The python way
for a single application (as the one we defined earlier) we do not need to edit more files. Simply run:
./uwsgi -s /tmp/uwsgi.sock -C -w pippo_wsgi ** Starting uWSGI on [XXXX] *** your process address space limit is XXXX bytes (XXXX MB) your memory page size is XXXX bytes binding on UNIX socket: /tmp/uwsgi.sock chmod() socket to 666 for lazy and brave users ...getting the applications list from the 'pippo_wsgi' module... uwsgi.applications dictionary is not defined, trying with the (deprecated) "applications" one... applications dictionary is not defined, trying with the "application" callable. initializing [/] app... application 0 (/) ready setting default application to 0 request/response buffer (4096 bytes) allocated. spawned uWSGI worker 1 (pid: 4489)
the uWSGI server will try variuos python-way to configure the environment then it will fallback to single app mode sarching for an application callable (as the one you defined).
(if the uWSGI server cannot initialize apps on startup it will go in DynamicApps mode)
Now your app is ready to serve request from your webserver :
On Apache2 Load the uwsgi module (in apache config file):
LoadModule uwsgi_module /<path_of_apache_modules>/mod_uwsgi.so
Then define the <Location> that forwards requests to uwsgi:
<Location /pippo>
SetHandler uwsgi-handler
</Location>
Reload Apache and you are ready
Apache users warning !!!
If the <Location> specified has filesystem correspondence (exists in your document root) you have to fix the apache path_info handling using this directive:
<Location /pippo>
uWSGIforceScriptName /pippo
SetHandler uwsgi-handler
</Location>
Multiple uwsgi servers, only one apache
You can run all the uwsgi server you want (with the uid/gid you want), binding them on different UNIX socket.
Suppose you have 3 uwsgi servers running on /tmp/uwsgi1.sock, /var/lib/apache2/uwsgi.sock and /home/pippo/myuwsgi.sock
modify your apache configuration adding the uWSGIsocket directive:
<Location /one>
uWSGIsocket /tmp/uwsgi1.sock
SetHandler uwsgi-handler
</Location>
<Location /two>
uWSGIsocket /var/lib/apache2/uwsgi.sock
SetHandler uwsgi-handler
</Location>
<Location /three>
uWSGIsocket /home/pippo/myuwsgi.sock
SetHandler uwsgi-handler
</Location>
Mastering sockets
Remember that UNIX sockets are filesystem objects, so you have to check that permissions allow apache user (www-data on debian/ubuntu) to write on them.
The -C directive change the socket permissions to 666.
If you are on a Linux system you can use UNIX socket in the abstract namespace (no filesystem related). Add the -a flag to the uwsgi server command line and modify the uWSGIsocket directive (in apache) adding a @ in front of the socket name:
./uwsgi -s funnyuwsgisock -a -x myconfig.xml *** Starting uWSGI on [XXXXXXXXXXXXXXXX] *** binding on UNIX socket: /tmp/uwsgi.sock setting abstract socket mode (warning: only Linux supports this) parsing config file myconfig.xml interpreter for app 1 initialized. application 1 (/pippo) ready config file parsed. spawned uWSGI worker 0 (pid: XXXXX)
<Location /one>
uWSGIsocket @funnyuwsgisock
SetHandler uwsgi-handler
</Location>
Advanced logging and profiling
By default uwsgi logs on stderr. If you want to daemonize it and log on custom file, add the -d directive:
./uwsgi -s funnyuwsgisock -a -x myconfig.xml -d myserver.log
All the log message now goes into myserver.log
If you are on a Linux system, you can receive information of Address Space and RSS memory usage (useful before going in production on resource limited environment) after every request.
Add the flag -m to your uwsgi command line to enable it:
./uwsgi -s funnyuwsgisock -a -x myconfig.xml -m -d myserver.log
Every uwsgi request report on the logging system how much msecs are elapsed. This is useful to analyze application performance, but if you need more control you can enable the integrated python profiler (cProfile)
./uwsgi -s funnyuwsgisock -a -x myconfig.xml -m -d myserver.log -P
Self-healing
On Business/Enterprise environments, self-healing is an important player in the platform. There are two flag in uwsgi to drive this:
-t <timeout> (enable harakiri mode) -M (enable master process manager)
The harakiri mode set an alarm of <timeout> seconds before every request. If the timeout expires before the request conclusion (probably a bad symptom) the uwsgi process is killed. If you use a process manager as upstart (on ubuntu) or the daemontools, the process is automatically respawned. If your uwsgi server is not under a process manager you can use the integrated one adding the -M flag.
./uwsgi -s /tmp/uwsgi.sock -a -x myconfig.xml -M *** Starting uWSGI on [XXXXX] *** binding on UNIX socket: /tmp/uwsgi.sock setting abstract socket mode (warning: only Linux supports this) parsing config file myconfig.xml interpreter for app 1 initialized. application 1 (/pippo) ready config file parsed. spawned uWSGI master process (pid: XXXXX) Spawned uWSGI worker 1 (pid: XXXXX)
Multiple Python interpreters
By Default, every application served by uwsgi (configured via xml or with DynamicApps) initialize a new python interpreter. This ensure some form of isolation, but if you want to share the same interpreter for all of your app (to gain some memory, or to use some sort of app communication) you can add the -i flag. On python-only configuration (the one specified with the -w flag) single interpreter mode is forced.
Multiple uWSGI workers
You can increment concurrency adding more uwsgi processes:
-p <n> (spawn <n> process worker)
./uwsgi -s /tmp/uwsgi.sock -a -x myconfig.xml -M -p 6 *** Starting uWSGI on [XXXXXXXXXXXXX] *** binding on UNIX socket: /tmp/uwsgi.sock setting abstract socket mode (warning: only Linux supports this) parsing config file myconfig.xml interpreter for app 1 initialized. application 1 (/pippo) ready config file parsed. spawned uWSGI master process (pid: XXXXX) Spawned uWSGI worker 1 (pid: XXXXX) Spawned uWSGI worker 2 (pid: XXXXX) Spawned uWSGI worker 3 (pid: XXXXX) Spawned uWSGI worker 4 (pid: XXXXX) Spawned uWSGI worker 5 (pid: XXXXX) Spawned uWSGI worker 6 (pid: XXXXX)
Threading support
Adding multithread mode to the server is not of interest at this moment, but if your wsgi app generates Threads they can be executed without problem. To enable Threads add the -T flag. Python threads get cpu when the uwsgi server is not using the python environment.
Python Optimization
You can define the level of python engine optimization (0, 1 or 2) using the -O flag. Some application may not work well on higher optimization level.
CGI Mode
If you are using an esotic webserver, or your platform cannot compile the apache module, you can use the cgi mode of uwsgi.
adding the -c flag, uwsgi will became cgi-friendly.
In the uwsgi distribution are included 2 cgi (in pure C) that you can use as uwsgi client (to emulate the mod_uwsgi behaviour).
For example on Apache you can use the ScriptAlias? directive:
ScriptAlias /pippo /path_to_uwsgi_cgi
Obviously the cgi app must be in a cgi-enabled directory
If you are a user of Cherokee (and you do not want to use its UWSGI module) you can define a new Directory in your virtual server tha use CGI has handler. In the Script Alias directive set the full path of the cgi script.
In Lighttpd you need to modify che cgi client to set PATH_INFO and SCRIPT_NAME in a sane way.
Nginx has no official support for cgi.
TCP support
Starting from version 0.9.2 you can bind uWSGI on a TCP socket:
./uwsgi -s 127.0.0.1:3030
or (if you want to bind on all interfaces):
./uwsgi -s :3030
All the currently supported webserver handlers fully supports this configuration (so you can use it to build big clusters). Sadly on the Apache2 module load-balancing to multiple machines is not supported. Other webserver handlers support clustering without problems.
You can set the socket timeout using the second argument of the uWSGISocket option
uWSGISocket 127.0.0.1:3030 30
Best practice
Always configure your webserver to serve static content. On Apache you can use the Alias directive to map uri to filesystem directory.
For example you can map Trac's static content to /chrome and add an Apache Alias directive to map /chrome in trac's htdocs directory
Alias /chrome /usr/share/trac/htdocs
<Location /trac>
SetHandler uwsgi-script
</Location>
in your project's trac.ini:
[trac] ... htdocs_location = /chrome ...
If you have an application that use a lot of http headers or you are running uwsgi on a low memory system you can configure the buffer size (default to 4k):
./uwsgi -s /tmp/uwsgi2.sock -b 8192
...this will use a buffer of 8k for all the request/response data handling
If you want to serve unreliable python application with mod_uwsgi, its better to configure socket timeout using the second (optional) uWSGISocket's arg :
uWSGISocket /tmp/uwsgi.sock 30
In high-availability contests you can use (starting from version 0.9.1) the socket failover directive of apache mod_uwsgi:
uWSGISocket2 /tmp/uwsgi_failover.sock
If the connection to the first socket fails, mod_uwsgi try the second one binded by a second uwsgi server. This mode is useful when you are rebooting the uwsgi server for reloading your app but during this down-time you want to maintain the old app online.
Starting from version 0.9.1 the uwsgi server responds to SIGUSR1, printing application usage statistics:
killall -USR1 uwsgi *** pid 11602 stats *** total requests: 3 app 0 requests: 0 app 1 requests: 3 app 2 requests: 0 app 3 requests: 0
This statistics are a bit raw. The best way to get real useful data is using the EmbeddedModule
