What does sphinx-autobuild do?

sphinx-autobuild wraps `sphinx-build` with a file watcher and a development web server. When any source file in the watched directory changes, it triggers a rebuild and pushes a refresh signal to the connected browser. The result is a live-reload authoring loop similar to `mkdocs serve` for [MkDocs]({{ }}).

How is sphinx-autobuild different from sphinx-build?

`sphinx-build` performs a single one-shot build of the documentation. `sphinx-autobuild` runs `sphinx-build` once, then watches the source tree and re-invokes the same build whenever a file changes. It also serves the rendered HTML over HTTP and injects a small WebSocket script into each page so the browser refreshes without manual reload.

How do I install sphinx-autobuild?

Add it to a `[dependency-groups]` docs group with `uv add --group docs sphinx-autobuild`, or install globally with `pip install sphinx-autobuild`. Then run `sphinx-autobuild docs/source docs/build/html` from the project root. The default development URL is `http://127.0.0.1:8000`.

Should I use sphinx-autobuild in CI?

No. sphinx-autobuild is a developer tool for the local authoring loop. CI environments should call `sphinx-build` directly to produce a single artifact; the file watcher and HTTP server have no purpose in a non-interactive build.

sphinx-autobuild: Live Reload for Sphinx Documentation

by Tim Hopper

Documentation

sphinx-autobuild watches a Sphinx documentation source tree and rebuilds the HTML output every time a file changes. It also runs a small development web server and refreshes the browser automatically, replacing the edit-build-reload cycle with edit-and-look.

Note

sphinx-autobuild 2025.8.25 is the current stable release, licensed MIT. Install with uv add --group docs sphinx-autobuild or pip install sphinx-autobuild.

When to use sphinx-autobuild

Use sphinx-autobuild during local documentation work. It removes the friction of running make html (or sphinx-build) by hand after every edit and waiting for the browser to be refreshed. For one-shot CI builds, deploy artifacts, or scripts, call sphinx-build directly.

Key Features

Runs sphinx-build automatically on file changes
Built-in HTTP server (defaults to port 8000)
WebSocket-based browser refresh: open the page once and it stays in sync
Forwards command-line arguments to sphinx-build, so most existing build flags work unchanged
Optional --open-browser flag to launch the page on startup

Usage

Run sphinx-autobuild from the project root, pointing it at the source and output directories:

sphinx-autobuild docs/source docs/build/html

The tool prints a URL (http://127.0.0.1:8000 by default) and watches docs/source/ for changes. Edit a .rst or .md file, save, and the page reloads.

Common flags:

Flag	Purpose
`--port 9000`	Change the development server port
`--host 0.0.0.0`	Bind to all interfaces (LAN preview)
`--open-browser`	Open the URL in the system browser at startup
`--watch path`	Watch additional directories for changes
`--ignore path`	Skip changes in a specific path

Any unknown flag is forwarded to the underlying sphinx-build invocation, so existing -W, -n, or builder selection arguments still work.

Pros

Brings live reload to Sphinx, the same workflow mkdocs serve provides for MkDocs
Drop-in: forwards arguments to sphinx-build
Maintained by the Sphinx project itself (moved into the sphinx-doc/ GitHub organization in 2024)
No daemon to manage

Cons

Linux file-watching can miss events under certain editors that use atomic-rename writes; tweaking --watch and --ignore may be needed
The development server is for local use only; no authentication, no TLS
Forces a full rebuild on every change rather than partial recompilation

Learn More

GitHub Repository
PyPI Page
Sphinx Reference
Furo Reference (common Sphinx theme used alongside)

Last updated on April 29, 2026

Sphinx tox

Please submit corrections and feedback...