Skip to main content

WSGI middleware to send files using X-Accel-Redirect

Project description

WSGI Middleware to Support X-Accel-Redirect build status


Nginx has a mechanism whereby, by returning an X-Accel-Redirect header, a web app may convince nginx to serve a static file directly. PEP 333 defines a mechanism whereby an app server (or middleware) can offer to serve files directly by providing wsgi.file_wrapper in the environ. This package provides a piece of WSGI middleware to take advantage of those two mechanisms.

Despite the name of the package, currently this middleware only works with nginx’s X-Accel-Redirect mechanism. (It would probably be straightforward to generalize it so that it works X-Sendfile, but at the moment, I have no need for that.)

Download & Source

The source repository is on github. You may submit bug reports and pull requests there.

It is also available via PyPI.


The middleware is xsendfile_middleware.xsendfile_middleware. You can call it directly, e.g.:

from xsendfile_middleware import xsendfile_middleware

def main(**settings):
    """ Construct and return a filtered app.
    def my_app(environ, start_response):
        # ...
        return app_iter

    # wrap middleware around app
    return xsendfile_middleware(my_app)

There is also a suitable entry point provided so that you can instantiate the middleware from a PasteDeploy .ini file, e.g.:

use = egg:MyEgg

pipeline = egg:xsendfile_middleware myapp



Once you have the middleware in place, the only configuration needed (or possible) is to set an X_REDIRECT_MAP key in the WSGI environ. How you do that depends on how you’ve got things set up. If you are running your app under uwsgi, for example, then you can use something like the following in your nginx config:

location /app {
  include uwsgi_params;

  uwsgi_param X_REDIRECT_MAP /path/to/files/=/_redir_/;

location /_redir_/ {
  alias /path/to/files/;

In this configuration, if your app returns an app_iter which is an instance of the file wrapper provided by the middleware, and that wrapper wraps file at, e.g., /path/to/files/dir/, the middleware will set an X-Accel-Redirect: /_redir_/dir/ header in the response. (This, hopefully, will cause nginx to send the desired file directly to the client.)

The format of X_REDIRECT_MAP is a comma-separated list of “/prefix/=/base_uri/” mappings. As a short-cut, “/prefix/” (with no equals sign) means the same as “/prefix/=/prefix/” (an X-Accel-Redirect header containing the original file name will be sent for matching paths.) The entries in the map are checked in order; the first matching entry wins. If none of the entries match, then the middleware will pass the response on up the chain unmolested.

Warning: The parsing of X_REDIRECT_MAP is rather simplistic. Things will probably not go well if you try to include commas, equal signs, or any non-ASCII characters in either the prefix or base_uri. Also, do not include any extraneous white space in X_REDIRECT_MAP.


This package was written by Jeff Dairiki.


0.1.1 (2016-10-28)

(Release 0.1 does not exist. It had corrupt rST in its PKG-INFO causing the README on PyPI not to be formatted.)

No changes (other than test configuration) from 0.1a3. This package has been used in production for years now — might as well drop the “alpha” designation.


  • Drop support for python 3.2. Now tested under pythons 2.6, 2.7, 3.3, 3.4, 3.5, pypy and pypy3.

0.1a3 (2015-05-08)

Brown bag. The previous release was unusable do to this bug:

  • Make sure not to include unicode strings in the headers passed to start_response.

0.1a2 (2015-05-08)

  • Py3k, pypy compatibility: the tests now run under python 2.6, 2.7, 3.2, 3.3, 3.4, pypy and pypy3.

0.1a1 (2013-12-11)

Initial Release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xsendfile_middleware-0.1.1.tar.gz (8.2 kB view hashes)

Uploaded Source

Built Distribution

xsendfile_middleware-0.1.1-py2.py3-none-any.whl (11.4 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page