Install & Compatibility
Where this runs
tested against v2.1.0 · 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.232s · 96.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.0s · import 0.218s · 97MB
99MB installed
● package 99MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QiskitSphinxTheme
✓ from qiskit_sphinx_theme import __version__
✗ import qiskit_sphinx_theme
Direct import of the module is fine, but to get version use __version__
html_theme
✓ html_theme = 'qiskit_sphinx_theme'
✗ html_theme = 'qiskit-sphinx-theme'
Use underscore, not hyphen, in conf.py
Basic Sphinx configuration using qiskit-sphinx-theme as the HTML theme.
# conf.py
import os
project = 'My Qiskit Project'
# ... other settings
html_theme = 'qiskit_sphinx_theme'
html_theme_options = {
'logo_only': False,
'display_version': True,
}
# Ensure the extension is loaded
# extensions list may include qiskit_sphinx_theme if needed
Errors
Common errors & fixes
Theme 'qiskit_sphinx_theme' not found
The theme is not installed or the name is misspelled (e.g., used hyphen instead of underscore).
fixInstall correctly: pip install qiskit-sphinx-theme, and in conf.py use html_theme = 'qiskit_sphinx_theme'
WARNING: html_theme option 'qiskit-sphinx-theme' is not a valid theme name
Using hyphen in theme name in conf.py, but Sphinx expects underscore.
fixChange html_theme = 'qiskit_sphinx_theme'
Upgrade
Version history
2.1.0latest on PyPI · released May 19, 2026
Audit
Dependencies
sphinxrequiredRequired runtime dependency