Install & Compatibility
Where this runs
tested against v2.0.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 · 18.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinxcontrib.qthelp
✓ extensions = ['sphinxcontrib.qthelp']
✗ import sphinxcontrib_qthelp
Sphinx extensions are activated by adding their module name to the 'extensions' list in conf.py, not by direct Python import statements in typical usage.
To use sphinxcontrib-qthelp, add 'sphinxcontrib.qthelp' to the 'extensions' list in your Sphinx project's conf.py file. You can also set specific configuration options for the QtHelp builder, such as the basename, namespace, and title of the help file. After configuration, build the documentation using the 'qthelp' builder via the sphinx-build command.
# conf.py
# -- Project information -----------------------------------------------------
project = 'My QtHelp Project'
copyright = '2026, Author Name'
author = 'Author Name'
version = '0.1'
release = '0.1.0'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinxcontrib.qthelp' # Add this line to enable the extension
]
# -- Options for qthelp output -----------------------------------------------
# For a full list of options, see the Sphinx documentation.
qthelp_basename = 'MyProjectHelp'
qthelp_namespace = 'org.mycompany.myproject.help'
qthelp_title = 'My Project Documentation'
# Example of how to build from command line (after configuring conf.py):
# sphinx-build -b qthelp sourcedir builddir
Debug
Known issues
breakingVersion 2.0.0 of sphinxcontrib-qthelp requires Python >= 3.9. Older Python environments will need to use an older version of this package.fixEnsure your project uses Python 3.9 or newer, or pin sphinxcontrib-qthelp to a compatible older version (e.g., <2.0.0) for older Python environments.
affects: 2.0.0 and later
breakingThis package, like other `sphinxcontrib` extensions, tracks Sphinx versions closely. Newer versions of `sphinxcontrib-qthelp` (e.g., 2.0.0) may not be compatible with significantly older Sphinx installations (e.g., Sphinx < 5.0), leading to build failures. For older Sphinx setups, you might need to pin `sphinxcontrib-qthelp` to an older version (e.g., 1.0.3).fixAlign the `sphinxcontrib-qthelp` version with your Sphinx installation's compatibility requirements. Refer to the Changelog for specific version notes, or consider upgrading Sphinx if possible.
affects: All versions, depending on Sphinx compatibility
gotchaGenerating the final `.qch` QtHelp file requires the external `qcollectiongenerator` command-line tool. This tool is part of the Qt development tools and is not installed when you `pip install sphinxcontrib-qthelp`. Users must install Qt development packages (e.g., `qt-tools` or similar, depending on OS) separately.fixInstall the necessary Qt development tools for your operating system to ensure `qcollectiongenerator` is available in your PATH.
affects: All versions
gotchaPrior to Sphinx 2.0, several `sphinxcontrib` packages (including `qthelp`) were often bundled directly with Sphinx. For Sphinx 2.0 and later, these extensions must be explicitly installed via `pip`.fixAlways explicitly `pip install sphinxcontrib-qthelp` when working with Sphinx versions 2.0 or newer, even if you previously didn't need to.
affects: Sphinx 2.0 and later
Upgrade
Version history
2.0.0latest on PyPI · released Jul 29, 2024
Audit
Dependencies
SphinxrequiredThis is a Sphinx extension and requires Sphinx to function.