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 Python 3.8+. 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. Let's 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 %}

Themes can also extend other themes using the theme argument:

{% extends theme("base.html", theme="my_parent_theme") %}

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.

Source Distribution

flask-themer-2.0.0.tar.gz (7.0 kB view hashes)

Uploaded Source

Built Distributions

flask_themer-2.0.0-py3.8.egg (10.1 kB view hashes)

Uploaded Source

flask_themer-2.0.0-py3-none-any.whl (6.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page