Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!



mod_wsgi is an implementation of the Python Web Server Gateway Interface v1.0 for the Nginx web server.

Nginx is a fast asynchronous HTTP server.

The design of this software was in part influenced by the mod_wsgi module for Apache by Graham Dumpleton and obtainable from This software also contains code from the Apache mod_wsgi module and is being used here with the permission of Graham Dumpleton.


mod_wsgi has been tested with Nginx 0.5.34. Other versions may require patches (see patches/README).

Download the Nginx sources from and unpack it.

The sources of mod_wsgi can be downloaded from a Mercurial repository:

At the moment there is no stable release, so you need to download the latest revision (tip) or the latest tag.

The tip can be downloaded via the Mercurial web interface:

or cloning the repository:

hg clone

The latest tag can be found from:

To build Nginx, change to the directory which contains the Nginx sources, and run the configuration script making sure to add the path to the mod_wsgi sources using the --add-module option. It is recommended to enable debugging.

$ ./configure --add-module=/path/to/mod_wsgi/ --with-debug

Nginx will use as default prefix path the directory /usr/local/nginx.

Now you can build and install the software:

$ make

and as root:

$ make install


In the mod_wsgi distribution, there are some examples in the examples directory.


The design goals of mod_wsgi is: make everything as simple as possible, but not simpler.

Nginx is not Apache, it is not designed to support generic embedded modules.

If a module blocks, the entire application will blocks.

This is somewhat mitigated by the fact that Nginx uses an arbitrary number of worker process.

Unlike Apache, the number of worker processes in nginx is fixed.

So why do implement a wsgi module for nginx?

The reason is: because writing a module for an existing web server is easier that write a web server from scratch.

Nginx is a very efficient web server and its code and memory usage is very compact.

mod_wsgi can be used for a fast deployment with batteries included, as a replacement for the Python standard HTTP server.

mod_wsgi can also be used for a robust deployment with mod_proxy, as a replacement for a Python FastCGI implementation like flup.

In a shared hosting this is valuable, since mod_wsgi usually requires less resources than a pure Python server.


Since Nginx is a pure asynchronous server, without threads support, it is important to implement WSGI extensions for asynchronous programming:




wsgi_python_optimize n


wsgi_python_optimize 0


http, server, location


Directive sets the optimization level of the Python compiler.

This is equivalent to the -O option of the Python Interpreter.



wsgi_python_executable path


http, server, location


Directive sets the path to the python interpreter executable.

This value is used to find the Python run-time libraries relative to the interpreter executable.


Syntax:wsgi_python_home path
Context:http, server, location



wsgi_enable_subinterpreters on | off


wsgi_enable_subinterpreters off


http, server, location


Directive enables the use of sub interpreters.

When enabled, each WSGI application will be executed in a separate sub interpreter, unless wsgi_use_main_interpreter directive is used.

NOTE: some applications may have problems when executed inside a subinterpreter.



wsgi_pass_authorization on | off


wsgi_pass_authorization off


http, server, location


By default, as suggested by the CGI spec, mod_wsgi does not pass the Authorization header to the WSGI application.

Enable this directive if the WSGI application handles HTTP authentication.



wsgi_allow_ranges on | off


wsgi_allow_ranges off


http, server, location


Directive enables integrated support to partial HTTP requests, using the nginx range filter module.

NOTE: in the current version nginx supports ranges for single buffer responses only.



wsgi_script_reloading on | off


wsgi_script_reloading off


http, server, location


If enabled, mod_wsgi will check, at every request, if the WSGI script has been modified.

If the script has been modified, it will reload the application using the reload mechanism specified in the wsgi_reload_mechanism directive.



wsgi_reload_mechanism module | process


wsgi_script_reloading module


http, server, location


This directive specifies how to reload a WSGI application whose file has been modified.

When module mechanism is in use, mod_wsgi will remove the script module from the system modules dictionary and will reload it.

When process mechanism is in use, mod_wsgi will raise a QUIT signal. This signal will request Nginx to do a graceful shutdown of the process (see the Nginx documentation for detailed info). The current request is served using the old WSGI application, but mod_wsgi will add a Refresh: 0 header, so that clients that recognize this header can execute a new request to obtain the updated resource.


it is possible to reload a WSGI application by sending a HUP signal to the master process.

See for more info.

WARNING: if the master process is not active, the Nginx process will be terminated.



wsgi_optimize_send_headers on | off


wsgi_optimize_send_headers off


http, server, location


Directive enables to optimize away content generation, when HTTP request does not requires a response body (as an example for HEAD request, or for a GET request when the client has a fresh cache of the resource entity).

For an effective use of this optimization, the WSGI application must return a generator and yield an empty string after having called start_response.

NOTE: WSGI spec explicitly requires that the headers must be sent when the first not empty string is yielded.



wsgi_output_buffering on | off


wsgi_output_buffering off


http, server, location


When output buffering is enabled, Nginx can buffer the data yielded by the WSGI application iterable.

This increments the performance, especially if the application yield small strings.

Note however that the WSGI spec recommend that the buffering should be done by the application and not by the gateway.

BUG: there seems to be problems when this directive is enabled.



wsgi_write_buffering on | off


wsgi_write_buffering off


http, server, location


This directive activates buffering of the write callable.

If buffering is activated, then mod_wsgi will store all the data written by the WSGI application in a buffer, assigned by directive wsgi_write_buffer_size.

The headers will be sent only when the WSGI application returns.

If the data can not all be placed in memory, then parts of it will be written to disk.

If buffering is switched off, then the data is synchronously transferred to client immediately.

NOTE: WSGI explicitly requires that the WSGI gateway must not buffer the data.

NOTE: sending data synchronously can have a severe impact on nginx performances.



wsgi_write_buffer_size buffer_size


wsgi_write_buffer_size 4k/8k


http, server, location


This directive controls the size of the buffer to use.

By default, the size of the buffer is equal to the size of page. Depending on platform this is either 4K or 8K.


Syntax:wsgi_temp_path dir-path [ level1 [ level2 [ level3 ] ] ]
Default:$NGX_PREFIX/wsgi_temp controlled by NGX_HTTP_WSGI_TEMP_PATH in configure script
Context:http, server, location
Description:This directive works like client_body_temp_path to specify a location to buffer large data generated by the write callable, if wsgi_write_buffering is enabled.



wsgi_var variable value


http, server, location


Directive assigns the variable, which will be added to the environment dictionary passed to the WSGI application.

It is possible to use strings, nginx variables and their combination as values. Directives not set are inherited from the outer level.


variables defined using this directive are added to the environment dictionary after HTTP headers, so user can override these values.

It can be useful, as an example, to override HTTP_COOKIE with:

wsgi_var HTTP_COOKIE  $http_cookie;

since the $http_cookie variable combines multiple Cookie headers.



wsgi_use_main_interpreter on | off


wsgi_use_main_interpreter off


http, server, location


Directive enables the execution of the WSGI application using the main Python interpreter.

This directive is only used when wsgi_enable_subinterpreters directive is enabled.


Syntax:wsgi_middleware module_name [callable_name]
Default:wsgi_pass module_name "middleware"
Context:http, server, location
Description:Directive push the specified middleware in the middleware stack.


Syntax:wsgi_pass module_path [callable_name]
Default:wsgi_pass module_path "application"
Context:location, if in location, limit_except
Description:Directive assigns the module path and the callable name of the WSGI application to execute.

Environment Dictionary

The environment dictionary supplied by the nginx WSGI module is built from user defined variables (see the wsgi_vars file).

The WSGI module for Nginx implements wsgi.file_wrapper for optional platform specific file handling.

Note that it is possible to choose whether to use sendfile via the sendfile option.



The WSGI module for Nginx supports the following extensions:


This extension allows WSGI applications to asynchronously poll for I/O events.

The ngx.poll extension is based on the Python stdlib select.poll interface.

There are two constants: ngx.WSGI_POLLIN and ngx.WSGI_POLLOUT. These are defined in the WSGI environment, but their value is "know" (0x01 and 0x04).

The ngx.connection_wrapper(fd) function takes as input a file descriptor (as integer) and returns a Connection wrapper object, to be used for later operations. Initially the connection is not bound to any request.

The Connection wrapper object has the following methods:


return the associated socket descriptor.


close the connection object, deregister it from the server "reactor" if still active and unbind the bounded request, if any.

XXX it also close the socket, even though this should be done by the client.

The function ngx.poll_register(flags) register the connection with the server "reactor" and bind it to the current request; flags is a bit mask of ngx.WSGI_POLLIN and ngx.WSGI_POLLOUT.

The function ngx.poll_deregister(flags=None) deregister the connection from the server "reactor" and unbit it from the bounded request.

The last function is ngx.poll(timeout).

When called, the user should yield an empty string (yielding a non empty string will result in an "undefined behaviour").

The WSGI application iteration will be suspended until a bound connection is ready for reading or writing, or the timeout (expressed in milliseconds) expires.

The ngx.poll function returns a callable that, when called, returns a tuple with the connection object "ready" (or None if timedout) and a flag indicating if the connection is ready for reading or writing.


due to the internal architecture of the Nginx event module (it have to support several different event systems), mod_wsgi for Nginx will only return ngx.WSGI_POLLIN or ngx.WSGI_POLLOUT, never ngx.WSGI_POLLIN | ngx.WSGI_POLLOUT.

Also, no error status is reported.

Recent activity

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.