Material for Sphinx

This theme is an adaptation of the popular mkdocs-material theme for the Sphinx documentation tool.

This theme is regularly maintained to stay up to date with the upstream mkdocs-material repository. The HTML templates, JavaScript, and styles from the mkdocs-material theme are incorporated directly with mostly minor modifications.

Independent of the upstream mkdocs-material theme, this theme integrates with and significantly extends Sphinx’s API documentation functionality.

This theme is a fork of the sphinx-material theme, which proved the concept of a Sphinx theme based on an earlier version of the mkdocs-material theme, but has now significantly diverged from the upstream mkdocs-material repository.

Getting Started


From the PyPI

pip install sphinx-immaterial

From git source

pip install git+


Building the theme from source requires node.js v14 or newer installed. Please be aware that uses a docker image that might have an outdated version of node.js installed. Installing node.js from a Unix package manager may not provide version 14 or newer.

Installing from a distributed wheel (such as from does not require node.js installed.

Sphinx configuration

Update your with the required changes:

extension = ["sphinx_immaterial"]
# ...
html_theme = "sphinx_immaterial"

There are a lot more ways to customize this theme. See Customization or theme.conf for more details.

Settings used in this documentation

html_theme = "sphinx_immaterial"

# material theme options (see theme.conf for more information)
html_theme_options = {
    "icon": {
        "repo": "fontawesome/brands/github",
        "edit": "material/file-edit-outline",
    "site_url": "",
    "repo_url": "",
    "repo_name": "Sphinx-Immaterial",
    "edit_uri": "blob/main/docs",
    "globaltoc_collapse": True,
    "features": [
        # "navigation.tabs",
        # "toc.integrate",
        # "navigation.instant",
        # "header.autohide",
        # "navigation.tracking",
        # "search.highlight",
    "palette": [
            "media": "(prefers-color-scheme: light)",
            "scheme": "default",
            "primary": "light-green",
            "accent": "light-blue",
            "toggle": {
                "icon": "material/lightbulb-outline",
                "name": "Switch to dark mode",
            "media": "(prefers-color-scheme: dark)",
            "scheme": "slate",
            "primary": "deep-orange",
            "accent": "lime",
            "toggle": {
                "icon": "material/lightbulb",
                "name": "Switch to light mode",
    # BEGIN: version_dropdown
    "version_dropdown": True,
    "version_info": [
            "version": "",
            "title": "ReadTheDocs",
            "aliases": [],
            "version": "",
            "title": "Github Pages",
            "aliases": [],
    # END: version_dropdown
    "toc_title_is_page_title": True,
    # BEGIN: social icons
    "social": [
            "icon": "fontawesome/brands/github",
            "link": "",
            "name": "Source on",
            "icon": "fontawesome/brands/python",
            "link": "",
    # END: social icons
Migrating from another theme

Be advised to clean prior builds before the first build with a new theme.

Last update: Apr 16, 2024