The redirects app¶
Django comes with an optional redirects application. It lets you store
redirects in a database and handles the redirecting for you. It uses the HTTP
response status code 301 Moved Permanently
by default.
Installation¶
To install the redirects app, follow these steps:
- Ensure that the
django.contrib.sites
framework is installed. - Add
'django.contrib.redirects'
to yourINSTALLED_APPS
setting. - Add
'django.contrib.redirects.middleware.RedirectFallbackMiddleware'
to yourMIDDLEWARE
setting. - Run the command
manage.py migrate
.
How it works¶
manage.py migrate
creates a django_redirect
table in your database. This
is a lookup table with site_id
, old_path
and new_path
fields.
The RedirectFallbackMiddleware
does all of the work. Each time any Django application raises a 404
error, this middleware checks the redirects database for the requested
URL as a last resort. Specifically, it checks for a redirect with the
given old_path
with a site ID that corresponds to the
SITE_ID
setting.
- If it finds a match, and
new_path
is not empty, it redirects tonew_path
using a 301 (“Moved Permanently”) redirect. You can subclassRedirectFallbackMiddleware
and setresponse_redirect_class
todjango.http.HttpResponseRedirect
to use a302 Moved Temporarily
redirect instead. - If it finds a match, and
new_path
is empty, it sends a 410 (“Gone”) HTTP header and empty (content-less) response. - If it doesn’t find a match, the request continues to be processed as usual.
The middleware only gets activated for 404s – not for 500s or responses of any other status code.
Note that the order of MIDDLEWARE
matters. Generally, you can put
RedirectFallbackMiddleware
at the
end of the list, because it’s a last resort.
For more on middleware, read the middleware docs.
How to add, change and delete redirects¶
Via the admin interface¶
If you’ve activated the automatic Django admin interface, you should see a “Redirects” section on the admin index page. Edit redirects as you edit any other object in the system.
Via the Python API¶
-
class
models.
Redirect
¶ Redirects are represented by a standard Django model, which lives in django/contrib/redirects/models.py. You can access redirect objects via the Django database API. For example:
>>> from django.conf import settings >>> from django.contrib.redirects.models import Redirect >>> # Add a new redirect. >>> redirect = Redirect.objects.create( ... site_id=1, ... old_path='/contact-us/', ... new_path='/contact/', ... ) >>> # Change a redirect. >>> redirect.new_path = '/contact-details/' >>> redirect.save() >>> redirect <Redirect: /contact-us/ ---> /contact-details/> >>> # Delete a redirect. >>> Redirect.objects.filter(site_id=1, old_path='/contact-us/').delete() (1, {'redirects.Redirect': 1})
Middleware¶
-
class
middleware.
RedirectFallbackMiddleware
¶ You can change the
HttpResponse
classes used by the middleware by creating a subclass ofRedirectFallbackMiddleware
and overridingresponse_gone_class
and/orresponse_redirect_class
.-
response_gone_class
¶ The
HttpResponse
class used when aRedirect
is not found for the requested path or has a blanknew_path
value.Defaults to
HttpResponseGone
.
-
response_redirect_class
¶ The
HttpResponse
class that handles the redirect.Defaults to
HttpResponsePermanentRedirect
.
-