Apache support

Currently there are three uwsgi-protocol related apache2 modules available.


This is the original module. It is solid, but incredibly ugly and does not follow a lot of apache coding convention style.

mod_uwsgi can be used in two ways:

  • The “assbackwards” way (the default one). It is the fastest but somewhat far from the Apache2 API. If you do not use Apache2 filters (including gzip) for content generated by uWSGI, use this mode.

  • The “cgi” mode. This one is somewhat slower but better integrated with Apache. To use the CGI mode, pass -C to the uWSGI server.



All of the options can be set per-host or per-location. Don’t forget to use SetHandler uwsgi-handler.

uWSGISocket <path> [timeout] Absolute path and optional timeout in seconds of uwsgi server socket.

uWSGISocket2 <path> Absolute path of failover uwsgi server socket.

uWSGIServer <host:port> Address and port of an UWSGI server (e.g. localhost:4000).

uWSGIModifier1 <int> Set uWSGI modifier1.

uWSGIModifier2 <int> Set uWSGI modifier2.

uWSGIForceScriptName <value> Force SCRIPT_NAME (app name).

uWSGIForceCGIMode <on/off> Force uWSGI CGI mode for perfect integration with apache filters.

uWSGIForceWSGIScheme <value> Force the WSGI scheme var (set by default to “http”).

uWSGIMaxVars <int> Set the maximum allowed number of uwsgi protocol variables (default 128).

To pass custom variables use the SetEnv directive:

SetEnv UWSGI_SCRIPT yourapp

Example of app accessed via uwsgi server socket:

<Location "/app/*">
   SetHandler uwsgi-handler
   uWSGISocket /var/lib/uwsgi/app.sock 30


This is the latest module and probably the best bet for the future. It is a “proxy” module, so you will get all of the features exported by mod_proxy. It is fully “apache api compliant” so it should be easy to integrate with the available modules. Using it is easy; just remember to load mod_proxy and mod_proxy_uwsgi modules in your apache config.

ProxyPass /foo uwsgi://
ProxyPass /bar uwsgi://
ProxyPass / uwsgi://

The first two forms set SCRIPT_NAME respectively to /foo and /bar while the last one use an empty SCRIPT_NAME. You can set additional uwsgi vars using the SetEnv directive and load balance requests using mod_proxy_balancer.

<Proxy balancer://mycluster>
   BalancerMember uwsgi://
   BalancerMember uwsgi://
ProxyPass / balancer://mycluster

Pay attention to the last slash in the member/node definition. It is optional for non-empty SCRIPT_NAME/mountpoints but required for apps mounted in the root of the domain. Currently the module lacks the ability to set modifiers, though this will be fixed soon. An alternative is to set the plugin you want to use as the first one (0):

plugins = 0:php


mod_proxy_uwsgi is considered stable starting from uWSGI 2.0.6


If you want to use this module (and help the uWSGI project), report any bugs you find, rather than falling back to the ancient (and ugly) mod_uwsgi

Starting from Apache 2.4.9, support for Unix sockets has been added. The syntax is pretty simple:

ProxyPass / unix:/var/lib/uwsgi/app1.sock|uwsgi://uwsgi-uds-app1/
ProxyPass / unix:/var/lib/uwsgi/app2.sock|uwsgi://uwsgi-uds-app2/


As per apache documentation, the hostname part of the proxy address is ignored. However, if one wants to have different sockets for different apps within the same apache instance, the proxy address is used by apache to identify different proxy workers: if the proxy address is the same, only the firstly declared unix domain socket will get a worker and the secondly declared app will have no worker and won’t be reachable. A workaround this apache limitation (bug?) is to use different hostnames.


This module is based on the SCGI module written by Roger Florkowski.


This module is currently undocumented.