{"id":24492,"library":"qiskit-sphinx-theme","title":"Qiskit Sphinx Theme","description":"A Sphinx theme for Qiskit and Qiskit Ecosystem projects, currently at version 2.0.0. Provides a consistent look and feel for Qiskit documentation. Releases follow Qiskit's release cadence.","status":"active","version":"2.0.0","language":"python","source_language":"en","source_url":"https://github.com/Qiskit/qiskit-sphinx-theme","tags":["sphinx-theme","qiskit","documentation"],"install":[{"cmd":"pip install qiskit-sphinx-theme","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required runtime dependency","package":"sphinx","optional":false}],"imports":[{"note":"Direct import of the module is fine, but to get version use __version__","wrong":"import qiskit_sphinx_theme","symbol":"QiskitSphinxTheme","correct":"from qiskit_sphinx_theme import __version__"},{"note":"Use underscore, not hyphen, in conf.py","wrong":"html_theme = 'qiskit-sphinx-theme'","symbol":"html_theme","correct":"html_theme = 'qiskit_sphinx_theme'"}],"quickstart":{"code":"# conf.py\nimport os\n\nproject = 'My Qiskit Project'\n# ... other settings\n\nhtml_theme = 'qiskit_sphinx_theme'\nhtml_theme_options = {\n    'logo_only': False,\n    'display_version': True,\n}\n\n# Ensure the extension is loaded\n# extensions list may include qiskit_sphinx_theme if needed\n","lang":"python","description":"Basic Sphinx configuration using qiskit-sphinx-theme as the HTML theme."},"warnings":[{"fix":"Upgrade Sphinx: pip install 'sphinx>=4.0'","message":"Version 2.0.0 dropped support for Sphinx < 4.0. If you are using an older Sphinx, upgrade Sphinx first.","severity":"breaking","affected_versions":"2.0.0"},{"fix":"Set html_theme = 'qiskit_sphinx_theme'","message":"The theme name in conf.py must use underscores (qiskit_sphinx_theme) not hyphens.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install correctly: pip install qiskit-sphinx-theme, and in conf.py use html_theme = 'qiskit_sphinx_theme'","cause":"The theme is not installed or the name is misspelled (e.g., used hyphen instead of underscore).","error":"Theme 'qiskit_sphinx_theme' not found"},{"fix":"Change html_theme = 'qiskit_sphinx_theme'","cause":"Using hyphen in theme name in conf.py, but Sphinx expects underscore.","error":"WARNING: html_theme option 'qiskit-sphinx-theme' is not a valid theme name"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}