Install & Compatibility
Where this runs
tested against v0.6.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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 101.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.6s · import 0.000s · 102MB
104MB installed
● package 104MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinx_design
✓ extensions = ['sphinx_design']
sphinx-design is enabled by adding its module name to the 'extensions' list in your Sphinx project's conf.py, not via a direct Python 'import' statement.
To quickly enable `sphinx-design`, add `'sphinx_design'` to your `extensions` list in `conf.py`. After that, you can use its directives and roles (like `dropdown`, `card`, `grid`, `sd-icon`) directly in your reStructuredText or MyST Markdown files. The example demonstrates generating a `conf.py` and provides commented guidance for using directives in content files.
import os
def create_minimal_conf_py():
conf_content = '''
project = 'My Design Docs'
copyright = '2023, Author'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx_design'
]
html_theme = 'furo'
'''
with open('conf.py', 'w') as f:
f.write(conf_content)
# In a real scenario, you'd then create an index.rst or index.md like this:
# with open('index.rst', 'w') as f:
# f.write('''
# My Design Docs
# ==============
#
# .. dropdown:: Click Me!
# :color: primary
#
# This is a dropdown content block.
#
# .. card:: Feature Card
# :shadow: lg
# :text-align: center
#
# A simple card to highlight information.
#
# :::{link-button} https://example.com
# Visit Example
# :::
# ''')
print("Generated conf.py with sphinx_design extension enabled.")
print("To use directives, add them to your .rst or .md files (e.g., dropdown, card, grid).")
if __name__ == '__main__':
create_minimal_conf_py()
Debug
Known issues
breakingPython version compatibility changes frequently with major `sphinx-design` releases. For example, v0.7.0 dropped support for Python 3.9 and 3.10.fixAlways check the `sphinx-design` changelog before upgrading for the required Python version. For v0.7.0, Python >= 3.11 is required.
affects: 0.7.0, 0.5.0
breakingSphinx version compatibility is strictly managed. `sphinx-design` often drops support for older Sphinx versions while adding support for newer ones.fixConsult the `sphinx-design` changelog or PyPI `Requires: Sphinx` metadata for the exact Sphinx version range. For v0.7.0, Sphinx v6 support was dropped, implying Sphinx v7+ is expected.
affects: 0.7.0, 0.6.1, 0.5.0, 0.2.0
gotchaIcon sets (Material Design Icons, Octicons) are periodically updated, which may change available icons or require updates to existing icon names.fixRefer to the `sphinx-design` documentation for the latest supported icon names and categories if icons appear broken or are not found after an upgrade.
affects: All versions with icon updates (e.g., 0.7.0, 0.6.0, 0.3.0, 0.1.0)
gotchaThe `sd_custom_directives` configuration option, allowing definition of custom directives with default options, was introduced in v0.6.0. Users on older versions cannot use this feature.fixUpgrade to `sphinx-design` v0.6.0 or newer to utilize the `sd_custom_directives` feature for advanced customization of directives.
affects: <0.6.0
Upgrade
Version history
0.7.0latest on PyPI · released Jan 19, 2026
Audit
Dependencies
SphinxrequiredCore dependency for building documentation. Specific Sphinx versions are required for different sphinx-design versions.