sphinx-immaterial

What it is and what it does

Sphinx-Immaterial is a Sphinx theme that brings the Material Design visual language to Sphinx-generated documentation. It adapts the popular mkdocs-material theme's HTML templates, JavaScript, and styles for use with Sphinx, the standard documentation tool for Python projects. The theme is regularly synchronized with upstream mkdocs-material to stay current with design updates.

The theme adds Sphinx-specific styling for API documentation (class and function descriptions) that mkdocs-material lacks, and implements search using Sphinx's native index format rather than lunr.js. It is installed as a Sphinx extension and configured by setting the html_theme variable in conf.py. Customization is supported through Jinja template block overrides placed in a project's _templates directory.

Use it for:

• Building modern, responsive documentation for Python libraries and frameworks with Material Design aesthetics
• Migrating from mkdocs-material to Sphinx while preserving visual consistency and user experience
• Styling API reference documentation with built-in support for Sphinx object descriptions (classes, functions, modules)
• Creating branded documentation sites that integrate search, navigation, and custom header/footer elements via template overrides

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx documentation theme that adapts the Material Design aesthetic from mkdocs-material, providing a modern, responsive HTML output for Sphinx projects with integrated search and API documentation styling.

Yes, if you need a modern Sphinx theme with Material Design. The package is actively maintained, has low install friction, carries a permissive MIT license, and integrates well with Sphinx's standard extension ecosystem. The beta status (pre-1.0) means breaking changes are possible, but the current version is marked production-stable and has been in active use. No known security vulnerabilities.

Install

sphinx-immaterial on PyPI

pip install sphinx-immaterial

uv add sphinx-immaterial

poetry add sphinx-immaterial

Installing sphinx-immaterial

Before you install

Low install friction with a pure-Python wheel distribution. Actively maintained as of August 2026 with regular updates tracking the upstream mkdocs-material repository. Requires Python 3.10 or later.

License in practice

MIT-licensed core with additional Creative Commons and GNU FDL components for bundled reference data. Permissive license allows commercial and private use with attribution; derivative works permitted under the same terms.

Quickstart

pip install sphinx-immaterial

# In conf.py:
extensions = ["sphinx_immaterial"]
html_theme = 'sphinx_immaterial'

Requires Python 3.10 or later; Sphinx must be installed and configured with a conf.py file.

Verify before relying

• Whether breaking changes remain likely before a 1.0 release (description notes beta status but version is 0.13.9)
• Performance characteristics with large documentation sets or complex API documentation
• Extent of customization options beyond Jinja template block overrides

Package facts

Evidence: sphinx_immaterial-0.13.9-py3-none-any.whl

Tags

More Sphinx packages