{"id":1878,"library":"sphinx-autobuild","title":"Sphinx Autobuild","description":"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.","status":"active","version":"2025.8.25","language":"en","source_language":"en","source_url":"https://github.com/sphinx-doc/sphinx-autobuild","tags":["sphinx","documentation","autobuild","livereload","hot-reload","development"],"install":[{"cmd":"pip install sphinx-autobuild","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for building documentation. `sphinx-autobuild` invokes `sphinx-build`.","package":"sphinx"},{"reason":"Used for efficient file system watching.","package":"watchfiles"},{"reason":"Used as the ASGI framework for the web server.","package":"starlette"},{"reason":"ASGI server for serving the documentation.","package":"uvicorn"},{"reason":"Cross-platform colored terminal output.","package":"colorama"}],"imports":[{"symbol":"sphinx-autobuild (command-line)","correct":"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":{"code":"mkdir -p docs\ncd docs\nsphinx-quickstart\n# Accept defaults or customize, ensure separate source/build dirs\ncd ..\nsphinx-autobuild docs/source docs/build/html\n# Open your browser to http://127.0.0.1:8000 and edit docs/source/index.rst","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2025.08.25 (for 3.9-3.10 drop), >=2024.02.04 (for 3.8 and earlier drop)"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All 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.","message":"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.","severity":"breaking","affected_versions":"Older Sphinx projects with `Makefile`s when upgrading `sphinx-autobuild`"},{"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.","message":"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.","severity":"gotcha","affected_versions":"e.g., 2024.09.03, particularly with Python 3.9"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}