uWSGI

uWSGI is a fast (pure C), self-healing, developer-friendly WSGI server, aimed for professional python webapps deployment and development. Over time it has evolved in a complete stack for networked/clustered python applications, implementing message/object passing, RPC and process management. It uses the uwsgi (all lowercase) protocol for all the networking/interprocess communications. From the 0.9.5 release it includes a plugin loading technology that can be used to add support for other languages or platform. A Lua wsapi adaptor, a PSGI handler and an Erlang message exchanger are already available.

Current features are

  • 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
  • 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 and MacOSX 10.5/10.6)
  • support for funny architectures like SPARC64 or ARM
  • support for python-generated threads (configurable)
  • cgi mode for lazy users or ugly webservers (example cgi included)
  • harakiri mode for self-healing
  • vector based I/O to minimize syscall usage
  • hot-add of wsgi applications. See DynamicApps
  • static configuration option based on xml files, pure-python module using ApplicationsDict, wsgi file, environment variables or Paste
  • on the-fly configuration parameters. See ManagementFlag
  • integrated profiler (cProfiler)
  • support for multiple interpreter mode
  • support for python2.4, python2.5, python2.6 and python2.7
  • 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 wih 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
  • support for python3. Warning, the current WSGI standard does not mention UNICODE support, and python3.x support in general. Look at RunOnPython3k
  • fully integrable in Twisted environments using the included client resource adapter. See RunOnTwisted
  • 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
  • Tomcat handler to integrate python apps in J2EE environments
  • Support for VirtualEnv
  • 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
  • A Django app for managing the uWSGI server. See uWSGIDjangoApp
  • FastFuncs for simple pages
  • Transparent Erlang Integration. See ErlangIntegration (from version 0.9.5)
  • 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)
  • Async mode (from version 0.9.5) See AsyncSupport
  • Integrated Green Threads tecnology on top of async mode( see uGreen , from version 0.9.5)
  • Experimental Support for Stackless Python (every request is managed by a Tasklet) (from version 0.9.5)
  • integrated SNMP agent and nagios-friendly output (from version 0.9.5) See UseSnmp
  • Hook based request-management and plugin/shared_library loading via dlopen() (from version 0.9.5)
  • VirtualHosting mode (from version 0.9.6)

TODO

  • integrated support for wsgi middleware (is it really useful ?)
  • put some more code comments to gather external developers ;)
  • better anti-fork bombing policy (lesser dumb)
  • IPv6 support (targeted at 0.9.6 release)
  • SCTP support (experimental support is in 0.9.5 trunk, but no performance gain, still hard work needed)
  • Event Dispatcher (execute callable on external events like file changes, bonjour/avahi/dnssd message, timers...) (work started in 0.9.6-dev)
  • hash table over SharedArea (for ultra-fast integrated caching)
  • AIX support (targeted at 0.9.6)

Get it

Current (stable) release:

 http://projects.unbit.it/downloads/uwsgi-0.9.5.4.tar.gz

(released on 20100706)

Current (stable/lts) release:

 http://projects.unbit.it/downloads/uwsgi-0.9.4.5.tar.gz

(released on 20100706) LTS doc here: Doc094

mercurial repository (trunk, unstable, could not be easily compiled)

hg clone http://projects.unbit.it/hg/uwsgi

Use it

Start from Install section. When you are ready go to Doc page

You can view some configuration example at the Example page

Developers/users list

 http://lists.unbit.it/cgi-bin/mailman/listinfo/uwsgi

Twitter

 http://twitter.com/unbit

pkgsrc area

 http://pkgsrc.se/www/py-uwsgi

Gentoo ebuild

 http://packages.gentoo.org/package/www-servers/uwsgi

Ubuntu third party packages

 https://launchpad.net/~stevecrozz/+archive/ppa

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

All those systems works very well, but none of them is a real (and complete) deploy system. uWSGI want to be a complete solution with process management, long running task handling, rpc, cluster communication, load balancing, monitoring, resource limiting and all those annoying task that you delegate to tons of ugly/inefficient external script and sysadmin tasks. (think about those funny almost-working cron jobs you use to maintain your app healthy...)

The long-term objective is to totally "pluginize" the uWSGI platform and allow other technologies (PSGI, Rack, JSGI...) to take its benefit.

If you are searching for a simple wsgi-only server, uWSGI is not for you, but if you are building a real (production-ready) app that need to be rock-solid, fast and easy to distribute/optimize for various load-average, you will pathetically and morbidly fall in love (we hope) with uWSGI.

What about the protocol ?

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

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

|flag1|pktsize_byte1|pktsize_byte2|flag2|

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

|keysize_byte1|keysize_byte2|...string...|valuesize_byte1|valuesize_byte2|...string...|keysize_byte1|keysize_byte2|...string..................

It could be used for every web technology:

A ruby-rack module that uses the uwsgi protocol is on work and a preliminary (ugly) version is in the current trunk (urack.rb)

...And no, we are not reinventing the wheel. We are at low-level, binary management is easier and cheaper than string parsing, and we need every bit of power for our projects. if you want to convince yourself look at the official protocol documentation and you will understand why a new protocol was needed.

Can i use it in cluster environments ?

Yes, starting from version 0.9.2 you can bind uWSGI on a TCP (ipv4) port. For example, using the UWSGI Cherokee handler you can specify different uWSGI server running on different systems, or you can use the integrated upstream load balancer of Nginx. A future version of mod_uwsgi for apache will include an integrated load-balancer.

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

Future releases will include ipv6 support and support for new trasnsport protocol as SCTP.

From the 0.9.5 release an integrated uwsgi (the protocol) proxy load balancer is included to reduce the sysadmin work in configuring uWSGI clusters.

Why all those timeout configuration flag ?

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

Why most of the funny features are 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 a mail to info at unbit.it with the keyword 'uWSGI' in the subject. The mail should includes Company information and obviously your specific request. We will reply ASAP

Does it will allow me to run python apps on my ancient closed-mind isp ?

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

How does it compare to solutions like Passenger ?

Passenger is a really great product, but we are not interested in automagic configurations and extreme user-friendlyness. We are hacker/geek/tech/business - friendly, and we are really bad at writing software for "people" ;)

What about mod_wsgi (the apache one)

Its "daemon mode" is wonderful, and it is probably one of the best way to run python apps. We are against embedding interpreters in webservers so we are against its "non-daemon mode". A bit of uWSGI code is based on mod_wsgi ideas.

It is GPL2, can i use it in commercial products ?

Yes, the uWSGI server only executes your applications, it does not link with them in any way (even if we expose the uwsgi module to your app). The problem could rise on webservers integration modules, but we will try to choose the best license for them. Please if you are a software license expert subscribe to the mailing-list and post your ideas.

Where are the benchmarks ?

Are hidden in a secret crypt on a secret island on a secret planet. If you are a benchmark fan you can try to find them. Sorry, we do benchmarks only for regressions test, most of the time people want becnhmarks only for starting flames. If you really need them for your business you can search on some mailinglist (for example on the cherokee list we posted a simple benchmark with flup), or ask someone (else) to do them for you.

Harakiri mode ???

We host hundreds of unreliable WSGI 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 mode (from version 0.9.4): one that we define 'raw and a bit unreliable' (used for simple setup without a process manager) and another one that we define '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 get the SIGALRM it terminates itself. We call this 'a bit unrealible' cause your app or some module you use could overwrite (or simply cancel) the alarm with a simple call to alarm(). The second one use 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 set in its dedicated area a timestamp representing the time after the process will be killed. After every successfull request this timestamp is zeroed. If the master process finds a worker with a timestamp in the past it will kill it.

Does my application will run faster with uWSGI ?

Probably not. The biggest player in webapps deployment is the webapp itself. If you want a faster environment optimize your code or use technics like clustering or caching. We say that uWSGI is fast cause it introduces a very little overhead in the deploy structure.

What are the most important options for performance and robustness of 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 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 on production environment.

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 using HTTP as the protocol ?

Good question, bad response:

HTTP parsing is slow, really slow.

Why doing a complex task twice (the webserver has already done it) ?

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

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

Is it a FastCGI/SCGI + FLUP on steroids ?

Probably. From a low-level point of view they work in the same way. Do not spend too much time looking at the communication protocol (as a lot of people do) as the hard work is done by the uWSGI server that tries to manage your apps in the best possibile way.

Why my stress-test fails on higher load ?

Yann Malet has done a very good analysis on uWSGI at this link  http://yml-blog.blogspot.com/2009/12/flup-vs-uwsgi-with-cherokee.html and he faced the self-healing/rock-solid functions of the uWSGI server. His tests with a higher load has been rejected by the uWSGI server automatically, lefting his machine healthy. Obviously you can tune the uWSGI server in more dangerous way. (but please do not do it in production environment). In the near future we will let the uWSGI server dinamically adjust some of its default value based on the rate of requests.

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:

Cherokee

The uWSGI support is officially included in the Cherokee webserver. Cherokee is fast and lightweight, has a beatiful admin interface and a great community. Their support for uWSGI has been awesome since the begining and we recommend its use in every situation. The userbase of the Cherokee uWSGI handler is probably the biggest of all the others choice. It is commercialy supported by Unbit.

Nginx

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.

Apache2

This is the first module developed, it is stable but a bit hacky (it does not fully use 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.

Lighttpd

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, 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".

Twisted

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

Tomcat

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.

CGI

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

Can i use the plugin handlers in production envronment ?

It depends. This a list of available plugin and their status.

LUA WSAPI

It is the first real plugin developed. It works very well, but it is still not solid as the WSGI main handler.

PSGI

This is the first commercially supported plugin developed. It is well tested and already used on production sites.

Erlang integration

This is a key component of the uWSGI stack. It is very well tested and commercially supported.

Rack

Still in beta quality. Do not use it in production environment.

JSGI (spidermonkey based)

still in development phase