sphinx-autobuild: Live-Reload Sphinx Docs
sphinx-autobuild runs sphinx-build, then watches the source tree and serves a live-reloading preview on a local port.
sphinx-autobuild is the authoring companion to sphinx-build: edit an .rst file and the browser refreshes. It is for local work; CI should call sphinx-build directly.
What it does
sphinx-autobuild wraps sphinx-build with a file watcher and a small HTTP server. On any source change it rebuilds the affected pages and pushes a reload to connected browsers. It takes the same SOURCEDIR and OUTDIR positional arguments as sphinx-build.
Common usage
sphinx-autobuild docs docs/_build/html
# bind to all interfaces on a chosen port (e.g. inside a container)
sphinx-autobuild --host 0.0.0.0 --port 8000 docs docs/_build/htmlOptions
| Flag | What it does |
|---|---|
| --host <addr> | Interface to serve on (default 127.0.0.1) |
| --port <n> | Port for the preview server |
| --open-browser | Open the default browser on start |
| --ignore <glob> | Paths to exclude from the watcher |
| --watch <dir> | Additional directory to watch for changes |
In CI
Do not run sphinx-autobuild in CI: it never exits, so it will hang the job. Use plain sphinx-build -b html -W for pipelines and reserve autobuild for local preview or a devcontainer.
Common errors in CI
A job that hangs until it is killed almost always means sphinx-autobuild was used where sphinx-build was intended; swap the command. OSError: [Errno 98] Address already in use means the chosen --port is taken by another process. It passes through the same build errors as sphinx-build, including Warning, treated as error when -W is added.