Awesome Open Source
Awesome Open Source


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.

Alternatives To Wagtail Themes
Select To Compare

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Python (821,947
Theme (43,411
Django (35,215
Example App (1,856
Wagtail (543