Sphinx Autobuild

2025.8.25 · active · verified Thu Apr 09

Sphinx-autobuild is an invaluable Python library that extends Sphinx by automatically rebuilding documentation on file changes and providing a hot-reloading web server. This allows developers to see their documentation updates in real-time as they write. It is actively maintained, with frequent releases, and the current version is 2025.8.25.

Warnings

breaking Python 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.
Fix: Ensure 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.
gotcha When 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.
Fix: It 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`.
breaking Sphinx 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.
Fix: Refer to the `sphinx-autobuild` documentation or its GitHub README for the recommended `Makefile` integration syntax. Update your `Makefile` to reflect the latest target definition.
gotcha Some 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.
Fix: This 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.
gotcha Generated files (e.g., by `autosummary`, Jupyter notebooks in `_build/jupyter_execute/`) can sometimes trigger infinite rebuild loops if not properly ignored by the watcher.
Fix: Use 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`.

Install

pip install sphinx-autobuild Install latest version

Imports

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`.

Quickstart

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

view raw JSON →