Install & Compatibility
Where this runs
tested against v0.13.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 183.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 9.6s · import 0.000s · 183MB
183MB installed
● package 183MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinx_immaterial
✓ extensions = [
# ... other extensions
'sphinx_immaterial'
]
The theme itself must be enabled as a Sphinx extension in `conf.py`.
html_theme
✓ html_theme = 'sphinx_immaterial'
✗ html_theme = 'material' # or 'mkdocs-material'
The theme name for Sphinx is 'sphinx_immaterial', not 'material' or 'mkdocs-material'.
To quickly set up `sphinx-immaterial`, first initialize a Sphinx project using `sphinx-quickstart`. Then, modify the `conf.py` file to include `sphinx_immaterial` in your `extensions` list and set `html_theme = 'sphinx_immaterial'`. You can further customize the theme using `html_theme_options` in `conf.py`.
import os
import sys
# Minimal conf.py
project = 'My Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1'
extensions = [
'sphinx_immaterial',
'sphinx.ext.autodoc', # Example standard extension
]
html_theme = 'sphinx_immaterial'
html_theme_options = {
'icon': {
'repo': 'fontawesome/brands/github'
},
'site_url': 'https://example.com/docs/'
}
# Example index.rst (or index.md if markdown is enabled)
# You would typically generate this with sphinx-quickstart first.
# Replace with content of docs/index.rst or equivalent.
# This part is illustrative, not executed Python code.
# Example: docs/index.rst
# My Project
# ===========
#
# Welcome to my project's documentation!
#
# .. toctree::
# :maxdepth: 2
# :caption: Contents:
#
# module1
# module2
Debug
Known issues
breakingThe theme is still in beta, and breaking changes may be introduced in minor versions before reaching a stable 1.0 release.fixAlways review the release notes and changelogs before upgrading, especially for minor versions, and test your documentation build.
affects: <1.0.0
breakingOlder Sphinx versions are no longer supported. For example, support for Sphinx < 6 was dropped in `sphinx-immaterial` v0.13.2.fixEnsure your Sphinx installation meets the minimum version requirement specified in the `sphinx-immaterial` release notes. Upgrade Sphinx to a compatible version.
affects: <0.13.2 (for Sphinx < 6)
gotchaIncompatibility with newer Sphinx versions due to internal API changes is a recurring issue, notably with Sphinx >= 7.3.0 and Sphinx 9.x. This can lead to `ExtensionError` or `KeyError` during the build process.fixCheck GitHub issues or release notes for specific compatibility fixes. If encountering issues, try pinning your Sphinx version to the latest known compatible version with `sphinx-immaterial` until a fix is released for the theme.
affects: 0.11.x with Sphinx >=7.3.0, 0.13.x with Sphinx 9.x
gotchaUsing the `numpydoc` Sphinx extension in conjunction with `sphinx-immaterial` might lead to warnings or unexpected formatting, as the theme explicitly warns if `numpydoc` is used.fixReview `numpydoc` configuration and theme documentation for any specific guidelines. Consider adjusting `numpydoc` settings or carefully inspecting rendered output to ensure correct interpretation of docstrings.
affects: All versions
Upgrade
Version history
0.13.9latest on PyPI · released Feb 6, 2026
Audit
Dependencies
sphinxrequiredRequired for building documentation; compatibility with Sphinx versions is actively managed and has led to breaking changes.
pythonrequiredRuntime environment requirement.
pymdown-extensionsoptionalRequired for the optional 'keys' extension (e.g., sphinx_immaterial.kbd_keys) to process keyboard key directives.