Install & Compatibility
Where this runs
tested against v0.8.1 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 23.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 24MB
22MB installed
● package 22MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinx_bootstrap_theme
✓ import sphinx_bootstrap_theme
Imported to get the theme's path dynamically.
html_theme
✓ html_theme = 'bootstrap'
Sets the active HTML theme for Sphinx.
html_theme_path
✓ html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
Directs Sphinx to where the 'bootstrap' theme is located after installation.
To quickly use the theme, install it via pip, then update your Sphinx project's `conf.py` file with the specified imports and theme configuration. This snippet also shows common `html_theme_options`.
# conf.py
import os
import sys
import sphinx_bootstrap_theme
project = 'My Project'
copyright = '2026, My Team'
author = 'My Team'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon'
]
html_theme = 'bootstrap'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
html_theme_options = {
'bootstrap_version': '3', # Can be '2' or '3'
'navbar_sidebarrel': False, # Remove 'prev' and 'next' links from navbar
'navbar_links': [
("Home", "index"),
("About", "about"),
("GitHub", "https://github.com/your-org/your-project", True)
],
'bootswatch_theme': "flatly", # Example: "flatly", "journal", etc.
'navbar_title': "My Project Docs"
}
Debug
Known issues
gotchaThe theme supports Bootstrap v2.3.2 and v3.3.7. Bootstrap 3 has known limitations such as dropped support for sub-menus in the navigation. Ensure you set `bootstrap_version` in `html_theme_options` to your desired version (default is '3').fixExplicitly set `html_theme_options = {'bootstrap_version': '3'}` or `'2'` in your `conf.py` based on your needs. If compatibility issues arise, try '2'. affects: <=0.8.1
gotchaThe theme integrates its own jQuery (as `$jqTheme`) using `noConflict()` to avoid clashes with Sphinx's internal jQuery. Custom JavaScript that directly relies on `$` for jQuery might encounter conflicts or unexpected behavior.fixWhen writing custom JavaScript, use `$jqTheme` instead of `$` for jQuery operations if you need to interact with the theme's Bootstrap components, or ensure your custom JS is carefully isolated.
affects: <=0.8.1
breakingUpgrading Bootstrap versions (even within the theme) can break custom CSS or JavaScript that relies on specific Bootstrap class names or HTML structures, as these frequently change between major Bootstrap versions.fixReview the Bootstrap migration guides (e.g., Bootstrap 2 to 3, or 3 to 4/5 if using a different theme) and update your custom CSS/JS to match the new class names. For `v0.5.0`, `bootswatch_css_custom` override was removed in favor of idiomatic Sphinx CSS overrides.
affects: 0.5.0 and later (especially if upgrading from older versions)
gotchaIf `navbar_title` is not explicitly set in `html_theme_options`, the theme defaults to using the `project` variable from `conf.py`. This often includes version numbers which might not be desirable for a clean navigation bar title.fixSet `html_theme_options = {'navbar_title': 'Your Project Name'}` to control the exact title displayed in the navigation bar. affects: <=0.8.1
Errors
Common errors & fixes
Bootstrap theme isn't loading javascript parts / Navbar isn't working correctly
Often due to conflicts with existing jQuery or other JavaScript, or incorrect loading of theme's JS/CSS assets.
fixEnsure `html_theme_path` and `html_theme = 'bootstrap'` are correctly set in `conf.py`. Check browser console for JavaScript errors. Ensure no conflicting jQuery versions are loaded or that your custom JS uses `$jqTheme` for theme-related interactions.
Sidebar T.O.C isn't working / Table of contents not showing
Incorrect configuration of `html_sidebars` or issues with the theme's JavaScript responsible for rendering the table of contents.
fixVerify that `html_sidebars` is configured to include the global or local table of contents (e.g., `['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']`). Check theme options related to TOC depth. If using a custom `globaltoc.html`, ensure it's correct.
Theme not applying / Build errors after changing theme
New themes can sometimes conflict with existing Sphinx configuration options, particularly `html_sidebars`, `html_theme_path`, or `html_theme_config`.
fixTemporarily comment out or unset `html_sidebars`, `html_theme_path`, or `html_theme_config` in your `conf.py` and rebuild. If the build succeeds, reintroduce options one by one to identify the conflict.
Upgrade
Version history
0.8.1latest on PyPI · released Feb 3, 2022
Audit
Dependencies
SphinxrequiredCore documentation generator that this theme extends.