Version 319 (modified by unbit, 5 years ago) (diff)


Documentation - Download - Install - Example


uWSGI is a fast, self-healing and developer/sysadmin-friendly application container server coded in pure C.

Born as a WSGI-only server, over time it has evolved in a complete stack for networked/clustered web applications, implementing message/object passing, caching, RPC and process management.

It uses the uwsgi (all lowercase, already included by default in the Nginx and Cherokee releases) protocol for all the networking/interprocess communications.

It can be run in preforking mode, threaded, asynchronous/evented and supports various forms of green threads/coroutines (such as uGreen and Fiber).

Sysadmins will love it as it can be configured via several methods: command line, environment variables, XML, .ini, yaml files and via LDAP.

On top of all this, it is designed to be fully modular. This means that different plugins can be used in order to add compatibility with tons of different technology on top of the same core.

See the following table for a list of current plugins:

TechnologyAvailable from versionNotesStatus
Python 0.9.1 The first available plugin, supports WSGI (PEP333, PEP3333), Web3 from version 0.9.7-dev and FastFuncs. Works with VirtualEnv, Multiple Python interpreters, Python3k and has unique features like module aliasing, DynamicVirtualenv and uGreenStable
Lua0.9.5 Support wsapi, coroutine and threadsStable
Perl0.9.5 PSGI support. threading mode supportedStable
Ruby0.9.7-dev Rack and RubyOnRails support. A loop engine for Ruby 1.9 fibers is availableBeta, needs test reports
Erlang0.9.5 allows message exchanging between uWSGI and Erlang nodes. ErlangIntegrationStable
JVM0.9.7-dev allows integration between uWSGI and the JVM. An example WSGI-like (jwsgi) handler is availableBeta
mono0.9.7-dev still at early stage of development allows integration between uWSGI and MonoUnusable

Current Core Features

  • Written totally in C
  • Very fast (and simple) communication protocol for webservers integration (apache2, nginx, cherokee and lighttpd modules available)
  • Low memory footprint (thanks to the evil premature optimizations)
  • Support for multiple application in the same process/domain
  • A master process manager that will allows you to automatically respawn processes and monitor the stack status
  • Preforking mode to improve concurrency
  • Address space and rss usage reports
  • Advanced logging (even networked, see UdpLogging)
  • Static file serving via sendfile() (where available)
  • Portability (tested on Linux 2.6, Solaris/OpenSolaris, OpenBSD, NetBSD, DragonflyBSD, FreeBSD, MacOSX, Nexenta, and Haiku)
  • Support for funny architectures like SPARC64 or ARM
  • Support for threads (configurable, available from 0.9.7-dev)
  • CGI mode for lazy users or ugly webservers (example CGI included here and here)
  • 'Harakiri mode' for self-healing
  • Vector based I/O to minimize syscall usage
  • Hot-add of applications. See DynamicApps
  • On the-fly configuration parameters. See ManagementFlag
  • Big (professional) user-base (hundreds of production ready wsgi apps) thanks to its main development managed by the Italian ISP Unbit
  • Commercial support available (contact Unbit for informations)
  • All code is under GPL2 (but you can buy a commercial license if you want to modify it without releasing source code)
  • Configurable buffer size for low-memory system or to manage big requests
  • Customizable builds (you can remove unneeded functionality)
  • Intelligent worker respawner with a no-fork-bombing policy
  • Limit requests per worker
  • Process reaper for external process managers (as daemontools). Avoids zombie workers.
  • Per-request modifier for advanced users (See RunOnNginx for an example usage, and uwsgiProtocol for the modifiers list)
  • UNIX and TCP socket support
  • Graceful restart of worker processes and hot-plug substitution/upgrade of the uWSGI server using Signals. See uWSGIReload
  • A shared memory area to share data between workers/processes. See SharedArea
  • An integrated Spooler for managing long running task.
  • Message exchanging (via uwsgi protocol) for easy-implementation of distributed applications (look at ClusteredExamples)
  • Get statistics of all the workers using the EmbeddedModule
  • Integrated Async/Evented? Proxy for load-balancing and healtchecking of big clusters (from version 0.9.5)
  • Address space usage limiting (from version 0.9.5)
  • integrated SNMP agent and nagios-friendly output (from version 0.9.5) See UseSnmp
  • VirtualHosting mode (from version 0.9.6)
  • Embedded async/evented HTTP server for easy development/testing and load balancing (from version 0.9.6)
  • Emperor mode for massive hosting (from version 0.9.7)
  • Linux Cgroups and Namespaces support (from versione 0.9.7)
  • A Signal Framework for managing external events (file system modifications, timers...) SignalFramework
  • Shared Cache/Hashtable/Dictionary? see CachingFramework

Planned Features / TODO

Planned FeatureNotesTarget Release Version
Integrated support for wsgi middlewareIs this really useful?Unknown
More intelligent anti-fork-bombing policy.N/AUnknown
Advanced conditional loggingN/A0.9.6.5, improved in 0.9.7
Linux cgroups integrationSee UseCgroups0.9.7
SSL support w/ certificate client authenticationAllows remote management of the uWSGI stack.Unknown
Support for multiple listening socketsAlready in Mercurial repository, add more --socket options.0.9.7
Web3Please see PEP-444preliminary support in 0.9.7
IPv6 supportN/A0.9.8
SCTP supportExperimental support is in 0.9.5, but needs performance improvements.Unknown
AIX, Hurd and MorphOS supportN/A0.9.8
Improved Rack/Ruby? On Rails pluginN/A0.9.7
Add a message queuing system on top of the SpoolerMessage queuing system should support publish/subscribe. Should be able to export via the STOMP protocolUnknown

Get it

The current (stable) release can be downloaded from:

(Released on 20110317)

The old stable (long-term-support) release can be downloaded from:

(Released on 20110207)

Mercurial repository (trunk, unstable, may not be easily compiled)

hg clone

Use it

To get started with uWSGI, take a look at the Install section of this wiki. When you are finished installing, have a look at the Doc page in order to learn about the options available. You can also view some example configurations at the Example page.

Developers/Users? mailing list

Please note that with a large open source project such as uWSGI, the code and the documentation may not always be in sync. This mailing list is the best source for help regarding uWSGI.

Gmane mirror


pkgsrc area

Gentoo ebuild

Ubuntu packages

Frequently Asked Questions (FAQ)

Why does this project exist? There are already mod_wsgi, flup and lot of other protocols (fastcgi, scgi...). Is this faster or simpler to configure ?

All of those systems work very well, but not one of them is a real (and complete) deployment system. uWSGI wants to be a complete solution with;

  • Process management,
  • Long running task handling,
  • RPC,
  • Cluster communication,
  • Load balancing,
  • Monitoring,
  • Resource limiting

and all of those other annoying tasks that you delegate to tons of ugly/inefficient external scripts and sysadmin tasks to. It is our belief that keeping your app running smoothly shouldn't require effort.

If you are searching for a simple wsgi-only server, uWSGI may not be for you. Though, if you are building a real (production-ready) app that needs to be rock-solid, fast and easy to distribute/optimize for various loads, you will find yourself pathetically and morbidly in love (we hope) with uWSGI.

What about the protocol?

The uwsgi (all lowercase) protocol is derived from scgi but with binary string length representation and a 4 byte header that includes the size of the var block (16 bit length) and a couple of general-purpose bytes. A typical WSGI request translate to:

header (4 bytes, size is in little endian) :


WSGI env vars follow (this is a block of the size specified in the header, string size is 16 bit little endian):


And no, we are not reinventing the wheel. Binary management is much easier and cheaper than string parsing, and we need every bit of power for our projects. If you need proof, look at the official protocol documentation and you will understand why a new protocol was needed.

Can I use it in cluster environments?

Yes, this is one of the main features of the uWSGI stack. For example, using the uwsgi Cherokee handler you can specify different uWSGI servers running on different systems, or you can use the integrated upstream load balancer of Nginx.

On webserver handlers without load balancing (as Apache) you can use the integrated proxy.

Remember that the uWSGI server can pass string messages, Python dictionaries and even Python marshaled objects via its network protocol, so you can use it to build a complete clustered/distributed Python application. See Clustering and ClusteredExamples.

Why all those timeout configuration flags?

Good timeout choosing is the key for high-availability. Do not trust network applications that do not permit you to choose a timeout.

Why are most of the advanced features disabled on UNBIT systems?

Because most of the self-healing functions and resource management are integrated in the platform.

How can I buy commercial support for my company?

Write an email to info at with the word 'uWSGI' in the subject. The email you send should include company information and your specific request. We will reply as soon as possible.

Will this allow me to run Python apps on my ancient close-minded isp?

Probably not. The uWSGI server has no support for automagic configurations.

Where are the benchmarks?

Sorry, we only do "official" benchmarks for regression testing. If benchmarks are very important to you, you can search on the mailing list (for example on the cherokee list we posted a simple benchmark with flup), make your own benchmarks or search on Google.

What is 'Harakiri mode'?

We host hundreds of unreliable web apps on our servers. All of them run on hardly (at kernel level) constrained environments where having processes blocked for an implementation error will result on taking down an entire site. The harakiri mode has two operational modes (from version 0.9.4): one that we define as 'raw and a bit unreliable' (used for simple setup without a process manager) and another one that we define as 'reliable' that depends on the presence of the uWSGI process manager. The first one sets a simple alarm at the start of every request. If the process gets a SIGALRM, it terminates itself. We call this 'a bit unreliable' because your app or some module you use could overwrite (or simply cancel) the alarm with a simple call to alarm(). The second one uses a master process shared memory area (via mmap) that maintains statistics on every worker on the pool. At the start of every request, the worker sets in its dedicated area a timestamp representing the time after the process will be killed. After every successful request this timestamp is zeroed. If the master process finds a worker with a timestamp in the past it will kill it.

Will my app run faster with uWSGI?

Probably not. The biggest bottleneck in web app deployment is the web app itself. If you want a faster environment, optimize your code or use techniques such as clustering or caching. We say that uWSGI is fast because it introduces a very little overhead in the deployment structure.

What are the most important options for performance and robustness in the uWSGI environment?

By default uWSGI is configured with almost-good-for-all values. But when things start going wild, tuning is a must.

Increasing (or decreasing) timeout is important, as is modifying the socket listen queue size.

Think about threading. If you do not need Python threads, do not enable them.

If you are running only a single application you can disable multiple interpreters (-i option).

Always remember to enable the master process in production environments.

Adding workers does not mean "increasing performance", so choose a good value based on the kind of your app (IO-Bound, Cpu_Bound, IO-waiting...)

Why not simply use HTTP as the protocol?

Good question.

HTTP parsing is slow, really slow.

Why should we do a complex task twice? The web server has already done it!

The uwsgi protocol is very simple to parse for a machine. HTTP is very easy to parse for a human.

When humans are being used as servers, we will abandon the uwsgi protocol in favour of the HTTP protocol.

Why do you support multiple methods of configuration?

System administration is all about skills and taste. uWSGI tries to give sysadmins as much choice as possible based on personal-taste and integration with already available infrastructure. Having multiple methods of configuration is just one way we achieve this.

What is the best webserver handler?

It is very hard to give an answer on this topic. We will try to give you information on every one:


uWSGI support is officially included in the Cherokee webserver. Cherokee is fast and lightweight, has a beautiful admin interface and a great community. Their support for uWSGI has been awesome since the beginning and we recommend its use in most situations. The userbase of the Cherokee uWSGI handler is probably the biggest of all. It is commercially supported by Unbit.


The module is included in the official Nginx distribution from the 0.8.40 release. A 0.7.x version is maintained in the uWSGI package. This is a stable handler commercially supported by Unbit.


This is the first module developed, it is stable but could be better integrated with the Apache API. It is commercially supported by Unbit.

From the 0.9.6-dev version a second Apache2 module is included (mod_Ruwsgi) that is more apache-api friendly. mod_Ruwsgi is not commercially supported by Unbit.


This module is the last developed but its inclusion in the official lighttpd distribution has been rejected, as the main author consider the uwsgi protocol a "reinventing the wheel" technology while suggesting a FastCGI approach. We respect this position and we will continue to maintain the module as a third party one. There is currently no commercial support for this handler. We consider this module "experimental".


This is a "commodity" handler, useful mainly for testing applications without installing a full webserver. If you want to develop an uwsgi server, look at this module. RunOnTwisted


The included servlet can be used to forward requests from tomcat to the uWSGI server. It is stable, but currently lacks documentation. There is currently no commercial support for this handler.


The CGI handlers are for "lazy" installations. Their use in production environments is discouraged.


The uwsgi IIS handler is a commercial product. You can get information by emailing us at: info at unbit dot it