Skip to main content

Simple theme mechanism for Flask

Project description

PyPI PyPI - License GitHub Workflow Status


Simple theme support for flask apps.

Flask-Themer is inspired by the (seemingly) abandoned flask-themes project, but has been written from scratch for py3.7+ (or 3.6 with the dataclasses backport). However it is not immediately compatible with flask-themes and does not seek to be. Flask-Themer tries to have little opinion on how you actually structure your project and its themes and does not require a particular metadata format/file.

Flask-Themer releases follow Semantic Versioning. Flask-Themer has 100% test coverage and considers it an error to fall below 100%.


Install the latest release from PyPi:

pip install flask-themer

or get the latest development version from github:

git clone
cd flask-themer
python develop


Flask-Themer usage is usually very basic, and once setup you likely won't need to touch it again. Lets do a quickstart. Notice how we import render_template from flask_themer instead of flask.

Our looks like this:

from flask import Flask
from flask_themer import Themer, render_template

app = Flask(__name__)
themer = Themer(app)

def get_current_theme():
    # This is where you would look up the current user's theme if one was
    # logged in, for example.
    return 'default'

def hello_world():
    return render_template('hello.html')

And next to it we have a directory called themes with a directory called default inside of it. Our themes/default/hello.html looks like this:

Hello world!

That's it! By default Flask-Themer will look for a themes directory next to your project and assume all the directories inside of it are themes. You can change what directory it looks for with THEMER_DEFAULT_DIRECTORY, or specify the template loaders explicitly to overwrite the default:

from flask_themer import Themer, FileSystemThemeLoader

app = Flask(__name__)
themer = Themer(app, loaders=[
    FileSystemThemeLoader(app, os.path.join(

Using Themes From Templates

Two template globals are added once Flask-Themer is setup, theme() and theme_static() (just like flask-themes). These methods look up the currently active theme and look for the given path in that theme, returning a special path that Jinja can use to load it.

{% extends theme("base.html") %}

{% block header %}
    {{ super() }}
    <link rel="stylesheet" href="{{ theme_static("bootstrap.css") }}">
{% endblock %}

Theme Loaders

Theme loaders are the mechanism by which Flask-Themer discovers what themes are available. You can create a custom loader to get themes from a ZIP file, or a database for example. Usually if you create a new ThemeLoader you'll also need to create a new Jinja template loader so Jinja knows how to read individual templates. Lets do a very minimal example that loads just a single theme from a ZIP file.

from zipfile import ZipFile
from flask_themer import ThemeLoader, Theme
from jinja2.loaders import BaseLoader, TemplateNotFound

class ZipFileTemplateLoader(BaseLoader):
    def __init__(self, *args, archive, **kwargs):
        super().__init__(*args, **kwargs)
        self.archive = archive

    def get_source(self, environment, template):
            return (, None, False)
        except KeyError:
            raise TemplateNotFound(template)

class ZipFileThemeLoader(ThemeLoader):
    def __init__(self, path_to_zip):
        self.archive = ZipFile(path_to_zip)

    def themes(self):
        yield Theme(

    def get_static(self, theme, path):

And then to use our new loaders we update our previous example:

themer = Themer(app, loaders=[

Pretty simple right? You can see how we could easily create a loader to load multiple themes from an archive, or load a user's customized theme from a database.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for flask-themer, version 1.4.1
Filename, size File type Python version Upload date Hashes
Filename, size flask_themer-1.4.1-py3.7.egg (9.9 kB) File type Egg Python version 3.7 Upload date Hashes View
Filename, size flask_themer-1.4.1-py3-none-any.whl (6.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size flask-themer-1.4.1.tar.gz (6.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page