• Language: en

Middleware

Middleware is a framework of hooks into Django’s request/response processing. It’s a light, low-level “plugin” system for globally altering Django’s input or output.

Each middleware component is responsible for doing some specific function. For example, Django includes a middleware component, AuthenticationMiddleware, that associates users with requests using sessions.

This document explains how middleware works, how you activate middleware, and how to write your own middleware. Django ships with some built-in middleware you can use right out of the box. They’re documented in the built-in middleware reference.

Changed in Django 1.10:

A new style of middleware was introduced for use with the new MIDDLEWARE setting. If you’re using the old MIDDLEWARE_CLASSES setting, you’ll need to adapt old, custom middleware before using the new setting. This document describes new-style middleware. Refer to this page in older versions of the documentation for a description of how old-style middleware works.

Writing your own middleware

A middleware factory is a callable that takes a get_response callable and returns a middleware. A middleware is a callable that takes a request and returns a response, just like a view.

A middleware can be written as a function that looks like this:

def simple_middleware(get_response):
    # One-time configuration and initialization.

    def middleware(request):
        # Code to be executed for each request before
        # the view is called.

        try:
            response = get_response(request)
        except Exception as e:
            # Code to handle an exception that wasn't caught
            # further up the chain, if desired.
            ...

        # Code to be executed for each request/response after
        # the view is called.

        return response

    return middleware

Or it can be written as a class with a __call__() method, like this:

class SimpleMiddleware(object):
    def __init__(self, get_response):
        self.get_response = get_response
        # One-time configuration and initialization.

    def __call__(self, request):
        # Code to be executed for each request before
        # the view is called.

        try:
            response = self.get_response(request)
        except Exception as e:
            # Code to handle an exception that wasn't caught
            # further up the chain, if desired.
            ...

        # Code to be executed for each request/response after
        # the view is called.

        return response

In both examples, the try/except isn’t required if the middleware doesn’t need to handle any exceptions. If it is included, it should probably catch something more specific than Exception.

The get_response callable provided by Django might be the actual view (if this is the last listed middleware) or it might be the next middleware in the chain. The current middleware doesn’t need to know or care what exactly it is, just that it represents whatever comes next.

The above is a slight simplification – the get_response callable for the last middleware in the chain won’t be the actual view but rather a wrapper method from the handler which takes care of applying view middleware, calling the view with appropriate URL arguments, and applying template-response middleware.

Middleware can live anywhere on your Python path.

__init__(get_response)

Middleware classes must accept a get_response argument. You can also initialize some global state for the middleware. Keep in mind a couple of caveats:

  • Django initializes your middleware with only the get_response argument, so you can’t define __init__() as requiring any other arguments.
  • Unlike the __call__() method which get called once per request, __init__() is called only once, when the Web server starts.
Changed in Django 1.10:

In older versions, __init__ was not called until the Web server responded to its first request.

If you want to allow your middleware to be used in Django 1.9 and earlier, make get_response an optional argument (get_response=None).

Marking middleware as unused

It’s sometimes useful to determine at startup time whether a piece of middleware should be used. In these cases, your middleware’s __init__() method may raise MiddlewareNotUsed. Django will then remove that middleware from the middleware process and log a debug message to the django.request logger when DEBUG is True.

Activating middleware

To activate a middleware component, add it to the MIDDLEWARE list in your Django settings.

In MIDDLEWARE, each middleware component is represented by a string: the full Python path to the middleware’s class or function name. For example, here’s the default value created by django-admin startproject:

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

A Django installation doesn’t require any middleware — MIDDLEWARE can be empty, if you’d like — but it’s strongly suggested that you at least use CommonMiddleware.

The order in MIDDLEWARE matters because a middleware can depend on other middleware. For instance, AuthenticationMiddleware stores the authenticated user in the session; therefore, it must run after SessionMiddleware. See Middleware ordering for some common hints about ordering of Django middleware classes.

Hooks and application order

During the request phase, before calling the view, Django applies middleware in the order it’s defined in MIDDLEWARE, top-down. You can think of it like an onion: each middleware class is a “layer” that wraps the view.

Middleware see only the changes made by middleware that run before it. A middleware (and the view) is skipped entirely if a preceding middleware short-circuits by returning a response without ever calling get_response. That response will only pass through the middleware that have already run.

Similarly, a middleware that sees the request on the way in and doesn’t return a response is guaranteed that it will always see the response on the way back out. If the middleware also wants to see any uncaught exception on the way out, it can wrap its call to get_response() in a try/except.

Besides the middleware pattern described earlier, you can add two other methods to class-based middleware:

process_view()

process_view(request, view_func, view_args, view_kwargs)

request is an HttpRequest object. view_func is the Python function that Django is about to use. (It’s the actual function object, not the name of the function as a string.) view_args is a list of positional arguments that will be passed to the view, and view_kwargs is a dictionary of keyword arguments that will be passed to the view. Neither view_args nor view_kwargs include the first view argument (request).

process_view() is called just before Django calls the view.

It should return either None or an HttpResponse object. If it returns None, Django will continue processing this request, executing any other process_view() middleware and, then, the appropriate view. If it returns an HttpResponse object, Django won’t bother calling the appropriate view; it’ll apply response middleware to that HttpResponse and return the result.

Note

Accessing request.POST inside middleware before the view runs or in process_view() will prevent any view running after the middleware from being able to modify the upload handlers for the request, and should normally be avoided.

The CsrfViewMiddleware class can be considered an exception, as it provides the csrf_exempt() and csrf_protect() decorators which allow views to explicitly control at what point the CSRF validation should occur.

process_template_response()

process_template_response(request, response)

request is an HttpRequest object. response is the TemplateResponse object (or equivalent) returned by a Django view or by a middleware.

process_template_response() is called just after the view has finished executing, if the response instance has a render() method, indicating that it is a TemplateResponse or equivalent.

It must return a response object that implements a render method. It could alter the given response by changing response.template_name and response.context_data, or it could create and return a brand-new TemplateResponse or equivalent.

You don’t need to explicitly render responses – responses will be automatically rendered once all template response middleware has been called.

Middleware are run in reverse order during the response phase, which includes process_template_response().

Dealing with streaming responses

Unlike HttpResponse, StreamingHttpResponse does not have a content attribute. As a result, middleware can no longer assume that all responses will have a content attribute. If they need access to the content, they must test for streaming responses and adjust their behavior accordingly:

if response.streaming:
    response.streaming_content = wrap_streaming_content(response.streaming_content)
else:
    response.content = alter_content(response.content)

Note

streaming_content should be assumed to be too large to hold in memory. Response middleware may wrap it in a new generator, but must not consume it. Wrapping is typically implemented as follows:

def wrap_streaming_content(content):
    for chunk in content:
        yield alter_content(chunk)

Exception middleware

A middleware that does some custom exception handling might looks like this:

class ExceptionMiddleware(object):
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        try:
            response = self.get_response(request)
        except Exception as e:
            # Do something with the exception and possibly reraise it
            # unless you wish to silence it.
            ...
        return response

Middleware that wants to do something for all exception responses, an HTTP 404 for example, need to both catch the appropriate exception (e.g. Http404) and look for regular responses with the status code of interest. You can subclass ExceptionMiddleware if you want to transform exceptions into the appropriate response.

Upgrading pre-Django 1.10-style middleware

class django.utils.deprecation.MiddlewareMixin

Django provides django.utils.deprecation.MiddlewareMixin to ease providing the existing built-in middleware in both new-style and old-style forms and to ease similar conversions of third-party middleware.

In most cases, this mixin will be sufficient to convert a middleware with sufficient backwards-compatibility; the new short-circuiting semantics will be harmless or even beneficial to the existing middleware.

In a few cases, a middleware class may need more invasive changes to adjust to the new semantics.

For example, in the current request-handling logic, the handler transforms any exception that passes through all process_exception middleware uncaught into a response with appropriate status code (e.g. 404, 403, 400, or 500), and then passes that response through the full chain of process_response middleware.

In new-style middleware, a given middleware only gets one shot at a given response or uncaught exception “on the way out,” and will see either a returned response or an uncaught exception, but not both.

This means that certain middleware which want to do something with all 404 responses (for example, the RedirectFallbackMiddleware and FlatpageFallbackMiddleware in django.contrib.redirects and django.contrib.flatpages) now need to watch out for both a 404 response and an uncaught Http404 exception. They do this by subclassing ExceptionMiddleware.

Back to Top