Install & Compatibility
Where this runs
tested against v1.1.4 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 102.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.2s · import 0.000s · 103MB
106MB installed
● package 106MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
html_theme
✓ html_theme = "sphinx_book_theme"
To activate the theme, set 'html_theme' in your project's conf.py file. This is not a Python import in the traditional sense, but a configuration setting.
To quickly set up documentation with Sphinx Book Theme, first initialize a Sphinx project using `sphinx-quickstart`. Then, install the theme via pip. The core step involves modifying your `conf.py` file to set `html_theme = "sphinx_book_theme"` and optionally configure `html_theme_options` for features like a repository link. Finally, build your documentation using `make html` or `sphinx-build`.
# 1. Create a new Sphinx project (if you don't have one)
sphinx-quickstart
# 2. Install the theme
pip install sphinx-book-theme
# 3. Edit conf.py in your Sphinx project's source directory
# Add 'sphinx_book_theme' to the html_theme variable:
# html_theme = "sphinx_book_theme"
# Optionally, add theme options, e.g., for a GitHub button:
# html_theme_options = {
# "repository_url": "https://github.com/executablebooks/sphinx-book-theme",
# "use_repository_button": True,
# "path_to_docs": "docs", # relative path to docs root from repo root
# "home_page_in_toc": True,
# }
# 4. Create an index.rst (or .md if using MyST-parser) and other content files
# Example index.rst:
# ====================
# Welcome to My Book!
# ====================
#
# .. toctree::
# :hidden:
# :maxdepth: 2
# :caption: Contents
#
# page1
# page2
# 5. Build your documentation
make html # or sphinx-build -M html . _build
Debug
Known issues
gotchaThe Sphinx Book Theme project is currently in 'maintenance mode'. This means new feature development is unlikely, and bug fixes may be slower or depend on community contributions. Users should manage expectations for active development.fixBe aware of the project's status and consider contributing if urgent fixes or features are needed.
affects: All current and future versions under maintenance mode
breakingThe v1.0.0 release introduced a 'major refactor' of the theme's HTML structure and updated its base, PyData Sphinx Theme. Projects with existing custom CSS or HTML templates from pre-1.0 versions may require significant re-configuration and adjustments to maintain their appearance and functionality.fixThoroughly review your custom CSS and HTML templates against the new theme structure. Consult the official changelog and migration guides if available.
affects: 1.0.0 and later
gotchaAs 'sphinx-book-theme' heavily depends on 'pydata-sphinx-theme', updates to the parent theme can introduce unexpected style changes or require adjustments to `html_theme_options`. Specifically, versions 1.1.3 and 1.1.4 noted 'breaking style changes in pydata-sphinx-theme'.fixAfter upgrading, always rebuild and review your documentation for any visual regressions. Be prepared to update `html_theme_options` or custom CSS.
affects: 1.1.3, 1.1.4, and potentially others inheriting from updated PyData Sphinx Theme versions
gotchaA historical issue (Issue #496) reported that `sphinx-book-theme.css` was sometimes imported twice, which could prevent user-defined custom CSS from correctly overriding theme styles due to load order problems. While potentially fixed, users attempting deep CSS customization should be vigilant.fixIf experiencing issues with CSS overrides, check the generated HTML for duplicate CSS imports. Consider using more specific selectors or `!important` as a last resort, or investigate the theme's CSS build process.
affects: Older versions (pre-1.1.0); inspect rendered HTML for current status
Upgrade
Version history
1.4.0latest on PyPI · released Jul 19, 2026
Audit
Dependencies
sphinxrequiredRequired for generating documentation; theme builds on Sphinx's core functionality. Minimum version 7.0 for v1.2.0.
pydata-sphinx-themerequiredSphinx Book Theme inherits a lot of functionality and design rules from PyData Sphinx Theme. Minimum version 0.15.4 for v1.2.0.
pythonrequiredRequires Python 3.11 or newer.