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.3.0
Filename, size File type Python version Upload date Hashes
Filename, size flask_themer-1.3.0-py3.7.egg (9.7 kB) File type Egg Python version 3.7 Upload date Hashes View hashes
Filename, size flask_themer-1.3.0-py3-none-any.whl (6.8 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size flask-themer-1.3.0.tar.gz (5.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page