Django Redirects App Tutorial

URL redirects are a fundamental part of maintaining a production website. There are many reasons why you might want to redirect a user from one part of your website to another, but doing so correctly is important for a positive user experience and to maintain the maximium SEO (Search Engine Optimization) possible.

Django ships with a built-in redirects app to help manage redirects, but the official documentation is not particularly friendly to newcomers, hence this tutorial.

Set Up Django Redirects

The Django redirects app works alongside the sites framework, which is also built-in but not automatically installed. We, as Django developers, need a few pieces of setup to use both fully.

To configure the Sites framework, add it to the INSTALLED_APPS configuration in settings.py and set a SITE_ID. It is customary to define a web application with only one site as 1.

# settings.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "django.contrib.sites",  # new
]

SITE_ID = 1  # new

For completeness, you should run a migration now to update your database.

(.venv) $ python manage.py migrate
Operations to perform:
 Apply all migrations: admin, auth, contenttypes, sessions, sites
Running migrations:
 Applying sites.0001_initial... OK
 Applying sites.0002_alter_domain_unique... OK

Like the Sites framework, the redirects app is included in Django by default but requires some configuration. We will update INSTALLED_APPS, MIDDLEWARE, and again run a database migration. Note that when adding the middleware, it should be placed near the bottom to work properly since middleware is run from top to bottom for an HTTP request (and bottom to top for an HTTP response, but that is a topic for another day).

# settings.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "django.contrib.sites",
    "django.contrib.redirects",  # new
    # other local and 3rd party apps
]

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",
    # ... any other custom middleware ...
    "django.contrib.redirects.middleware.RedirectFallbackMiddleware",  # new
]

Now run migrations to create the necessary database tables for the redirects app to work.

(.venv) $ python manage.py migrate
Operations to perform:
 Apply all migrations: admin, auth, contenttypes, redirects, sessions, sites
Running migrations:
 Applying redirects.0001_initial... OK
 Applying redirects.0002_alter_redirect_new_path_help_text... OK

Our set up is complete. Let's explore two different approaches for using it.

Approach 1: Admin Interface

The Django admin is a user-friendly way to manage redirects without writing any code. It is ideal for quickly setting up a small number of redirects or for non-technical team members.

Log into the admin: the Redirects and Sites sections should be visible.

Click on the "+Add" button next to Redirects. It brings up a form to select a Site, a "redirect from" path, and a "redirect to" path. As noted on the page, use an absolute path for the former and either an absolute path or full URL for the latter.

Here is an example of adding a redirect from "example.com/old" to "example.com/new".

Once saved you will be sent to the main Redirects page where you can see and edit all existing redirects.

If you want to change the "example.com" portion of the site, click on the Sites section, and you can update the Domain Name or Display Name. The Display Name is the human-readable name for the site, used in the admin and in templates for identification. The Domain Name is used for URL generation and validation, such as in a sitemap.

Next Steps

The redirects app uses permanent (301) redirects by default, which is typically what you want for SEO purposes. It is important to regularly review your redirects and monitor performance on a production website, as a large number of redirects can impact performance, and you might look into caching options if this is an issue. Also, remember to use relative URLs for new paths to ease the transition between local, staging, and production environments. A final tip is to add tests to confirm that redirects are working as expected.

If you'd like additional tips on optimizing your Django website's SEO, check out the list of tutorials on this topic.