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,
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.
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
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
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
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.
Middleware classes must accept a
get_response argument. You can also
initialize some global state for the middleware. Keep in mind a couple of
- Django initializes your middleware with only the
get_responseargument, 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.
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,
get_response an optional argument (
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
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
To activate a middleware component, add it to the
MIDDLEWARE list in
your Django settings.
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
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', ]
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
Middleware ordering for some common hints about ordering of Django
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
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
Besides the middleware pattern described earlier, you can add two other methods to class-based middleware:
process_view(request, view_func, view_args, view_kwargs)¶
request is an
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_kwargs include the first view argument
process_view() is called just before Django calls the view.
It should return either
None or an
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.
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.
CsrfViewMiddleware class can be
considered an exception, as it provides the
csrf_protect() decorators which allow
views to explicitly control at what point the CSRF validation should occur.
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.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
Dealing with streaming responses¶
StreamingHttpResponse does not have a
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)
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)
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.
and look for regular responses with the status code of interest. You can
ExceptionMiddleware if you want
to transform exceptions into the appropriate response.
Upgrading pre-Django 1.10-style middleware¶
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
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
django.contrib.flatpages) now need to watch out for both a 404 response
and an uncaught
Http404 exception. They do this by subclassing