Install & Compatibility
Where this runs
tested against v4.3.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.000s · 102.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.8s · import 0.000s · 103MB
105MB installed
● package 105MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinx_toolbox
✓ # In conf.py
extensions = [
'sphinx.ext.autodoc',
'sphinx_toolbox',
'sphinx_toolbox.more_autodoc' # Or specific sub-extensions
]
✗ import sphinx_toolbox.some_feature
sphinx-toolbox components are typically enabled as Sphinx extensions in `conf.py` rather than imported directly as Python modules. Adding 'sphinx_toolbox' enables a set of default features, while 'sphinx_toolbox.more_autodoc' enables all enhanced autodoc features.
To quickly get started, install the library and then add 'sphinx_toolbox' and any desired sub-extensions (like 'sphinx_toolbox.more_autodoc') to the `extensions` list in your Sphinx project's `conf.py` file. This enables the enhanced features provided by the toolbox.
# conf.py
# Standard Sphinx extensions
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
]
# Add sphinx-toolbox extensions
extensions.extend([
'sphinx_toolbox', # Enables core toolbox features
'sphinx_toolbox.more_autodoc', # Enables all enhanced autodoc features
# Or enable specific sub-extensions individually, e.g.:
# 'sphinx_toolbox.collapse',
# 'sphinx_toolbox.github',
# 'sphinx_toolbox.installation',
])
# Project information
project = 'My Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1.0'
# Example of a sphinx-toolbox configuration option
# source_link_target = 'GitHub' # For sphinx_toolbox.source extension
sphinx-toolbox --version
Debug
Known issues
breakingIn version 4.0.0, the `sphinx_toolbox.source` module no longer automatically enables the `sphinx_toolbox.github` extension. If you have `source_link_target` set to `'GitHub'`, you must manually add `'sphinx_toolbox.github'` to your `extensions` list in `conf.py`.fixAdd `'sphinx_toolbox.github'` to the `extensions` list in your `conf.py` if you rely on GitHub source links via `sphinx_toolbox.source`.
affects: >=4.0.0
gotchaWhile the version cap for `sphinx-autodoc-typehints` was removed in `sphinx-toolbox` 3.1.0, some configuration options introduced in `sphinx-autodoc-typehints` after version 1.14.1 might not work as expected. This is because `sphinx-toolbox` customizes certain internal functions of `sphinx-autodoc-typehints`.fixIf encountering issues with `sphinx-autodoc-typehints` configuration, consider testing with `sphinx-autodoc-typehints` version 1.14.1 or earlier, or reviewing `sphinx-toolbox` documentation for known incompatibilities with newer `sphinx-autodoc-typehints` features.
affects: >=3.1.0
gotchaSphinx-toolbox frequently updates its compatibility with various Sphinx versions. Ensure that the installed `sphinx-toolbox` version is compatible with your Sphinx installation to avoid unexpected build errors or broken features. Refer to the changelog for specific Sphinx version support.fixAlways check the `sphinx-toolbox` changelog or documentation for compatible Sphinx versions when upgrading either library. Update `sphinx-toolbox` if you upgrade Sphinx, and vice-versa, to maintain compatibility.
affects: All versions
gotchaWhen using the `sphinx_toolbox.source` extension, the `source_link_target` configuration option must be set to either `'GitHub'` or `'Sphinx'` (case-insensitive). Providing any other value will result in an `InvalidOptionError` during the Sphinx build.fixEnsure `source_link_target` in `conf.py` is one of the valid string values: `'GitHub'` or `'Sphinx'`.
affects: All versions with `sphinx_toolbox.source`
Upgrade
Version history
4.3.0latest on PyPI · released Jul 28, 2026
Audit
Dependencies
SphinxrequiredCore dependency for all functionality. Compatibility with specific Sphinx versions is actively maintained and frequently updated.
sphinx-autodoc-typehintsoptionalCustomized by sphinx-toolbox for enhanced type hint documentation; configuration options from versions > 1.14.1 might not function as expected.