Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Site specific theme loader for Django Wagtail.

Build Status Coverage Status


  • Django >= 3.1
  • Wagtail > =2.12

For older version of Django & Wagtail please use wagtail-themes==0.3.0.

Example app

See the example app for a working multisite with two different themes.

Run make and the app will install all the necessary files and fixtures for you. You can login with admin:admin and check how and serve different themes.


Install the package

pip install wagtail-themes

Add wagtailthemes to your INSTALLED_APPS





Add ThemeMiddleware to your MIDDLEWARE.


Now make sure the ThemeLoader is added to your loaders config in the setting TEMPLATES. Note that Django by default adds APP_DIRS to the setting, which conflicts with defining your custom loaders config.

Also note that the ThemeLoader must be placed on the top of the list (otherwise default templates will be found first).

        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            os.path.join(BASE_DIR, 'templates'),
        # Remove 'APP_DIRS': True at this position
        'OPTIONS': {
            'context_processors': [
            'loaders': [

Important: please make sure you don't have django.template.loaders.cached.Loader in your loaders.

Now select where your themes are stored with the WAGTAIL_THEME_PATH settings which has a default value of None.


Note that the setting WAGTAIL_THEME_PATH is optional. We strongly recommend using this if you have a large set of themes to keep your template directory maintainable.

Finally define your to be used themes in the setting WAGTAIL_THEMES

    ('brand', 'Brand site'),
    ('personal', 'Personal site')


The ThemeLoader class searches for files in your (see settings above) defined DIRS config for TEMPLATES.

In this case templates files will be found in the following order (for this example code we have set brand as theme in our CMS)

  1. /myapp/templates/themes/brand/
  2. /myapp/templates/

Its wise to build your templates as you are used to and only override the template files you want to customize in your theme.