# sphinx-autobuild: Live Reload for Sphinx Documentation


sphinx-autobuild watches a [Sphinx](https://pydevtools.com/handbook/reference/sphinx.md) 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:

```bash
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](https://github.com/sphinx-doc/sphinx-autobuild)
* [PyPI Page](https://pypi.org/project/sphinx-autobuild/)
* [Sphinx Reference](https://pydevtools.com/handbook/reference/sphinx.md)
* [Furo Reference](https://pydevtools.com/handbook/reference/furo.md) (common Sphinx theme used alongside)