Install & Compatibility
Where this runs
tested against v2024.10.3 · 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 · 99.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.1s · import 0.000s · 100MB
102MB installed
● package 102MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinx-autobuild (command-line)
✓ This library is primarily designed for command-line use and does not expose a public Python API for direct programmatic import in typical application code. It's invoked as an executable `sphinx-autobuild`.
First, create a basic Sphinx project using `sphinx-quickstart`. Then, run `sphinx-autobuild` pointing to your Sphinx source and output directories. This will start a local web server that automatically rebuilds and hot-reloads your documentation in the browser upon changes.
mkdir -p docs
cd docs
sphinx-quickstart
# Accept defaults or customize, ensure separate source/build dirs
cd ..
sphinx-autobuild docs/source docs/build/html
# Open your browser to http://127.0.0.1:8000 and edit docs/source/index.rst
sphinx-autobuild --version
Debug
Known issues
breakingPython version compatibility has changed. With version 2025.08.25, support for Python 3.9 and 3.10 was dropped to align with Sphinx's compatibility. Earlier, version 2024.02.04 dropped support for Python 3.8 and older.fixEnsure your Python environment meets the `requires_python` specification (currently >=3.11) and update your Python version if necessary. Check the `NEWS.rst` file or PyPI for the latest supported Python versions.
affects: >=2025.08.25 (for 3.9-3.10 drop), >=2024.02.04 (for 3.8 and earlier drop)
gotchaWhen developing Sphinx HTML themes, incremental builds (`sphinx-build`'s default behavior) might not detect changes in non-document files (like theme files or static assets). This can lead to outdated documentation being served.fixIt is recommended to pass the `-a` option to `sphinx-autobuild` to force a complete rebuild of all pages. This ensures all pages reflect the latest state of your HTML theme, although it may result in slower builds. Example: `sphinx-autobuild -a docs/source docs/build/html`.
affects: All versions
breakingSphinx is gradually moving away from `Makefile` usage. If you are using an older `Makefile` generated by `sphinx-quickstart`, the `livehtml` target integration for `sphinx-autobuild` might not work as expected with newer versions.fixRefer to the `sphinx-autobuild` documentation or its GitHub README for the recommended `Makefile` integration syntax. Update your `Makefile` to reflect the latest target definition.
affects: Older Sphinx projects with `Makefile`s when upgrading `sphinx-autobuild`
gotchaSome users have reported issues where hot reloading did not work after saving changes, particularly with Python 3.9 and specific `sphinx-autobuild` versions (e.g., 2024.09.03). The browser would not refresh, and `_build` files might remain unmodified despite changes in source.fixThis issue was often related to specific Python 3.9 environments. If encountering this, try upgrading `sphinx-autobuild` to the latest version or using a newer Python version (e.g., 3.10+). Recreating the virtual environment sometimes resolves it.
affects: e.g., 2024.09.03, particularly with Python 3.9
gotchaGenerated files (e.g., by `autosummary`, Jupyter notebooks in `_build/jupyter_execute/`) can sometimes trigger infinite rebuild loops if not properly ignored by the watcher.fixUse the `--ignore` (glob expression) or `--re-ignore` (regular expression) options to tell `sphinx-autobuild` to disregard these directories or files when watching for changes. Example: `sphinx-autobuild --ignore '_build/*' --ignore '**/_templates/*' docs/source docs/build/html`.
affects: All versions
Upgrade
Version history
2025.8.25latest on PyPI · released Aug 25, 2025
Audit
Dependencies
sphinxrequiredCore dependency for building documentation. `sphinx-autobuild` invokes `sphinx-build`.
watchfilesrequiredUsed for efficient file system watching.
starletterequiredUsed as the ASGI framework for the web server.
uvicornrequiredASGI server for serving the documentation.
coloramarequiredCross-platform colored terminal output.