# sphinx-autobuild
> Rebuild Sphinx documentation on changes, with hot reloading in the browser.
- **URL**: https://www.freshcrate.ai/projects/sphinx-autobuild
- **Author**: Adam Turner
- **Category**: Frameworks
- **Latest version**: `2025.8.25` (2026-04-21)
- **License**: Unknown
- **Source**: https://github.com/sphinx-doc/sphinx-autobuild/blob/main/NEWS.rst
- **Homepage**: https://pypi.org/project/sphinx-autobuild/
- **Language**: Python
- **GitHub**: 604 stars, 95 forks
- **Registry**: pypi (`sphinx-autobuild`)
- **Tags**: `pypi`
## Description
================
sphinx-autobuild
================
.. image:: https://img.shields.io/pypi/v/sphinx-autobuild.svg
:target: https://pypi.org/project/sphinx-autobuild/
:alt: Package on PyPI
.. image:: https://img.shields.io/badge/License-MIT-blue.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT
Rebuild Sphinx documentation on changes, with hot reloading in the browser.
.. image:: ./docs/_static/demo.png
:align: center
:alt: preview screenshot
Installation
============
sphinx-autobuild is available on `PyPI `__.
It can be installed using pip:
.. code-block:: bash
pip install sphinx-autobuild
Usage
=====
To build a classical Sphinx documentation set, run:
.. code-block:: bash
sphinx-autobuild docs docs/_build/html
This will start a server at http://127.0.0.1:8000
and start watching for changes in the ``docs/`` directory.
When a change is detected in ``docs/``, the documentation is rebuilt
and any open browser windows are reloaded automatically.
``KeyboardInterrupt`` (``ctrl`` + ``c``) will stop the server.
Command line options
====================
sphinx-autobuild accepts the same arguments as ``sphinx-build``
(these get passed to sphinx-build on each build).
It also has a few additional options,
which can seen by running ``sphinx-autobuild --help``:
.. code-block:: console
$ sphinx-autobuild --help
usage: sphinx-autobuild [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
...
autobuild options:
--port PORT port to serve documentation on. 0 means find and use a free port
--host HOST hostname to serve documentation on
--re-ignore RE_IGNORE
regular expression for files to ignore, when watching for changes
--ignore IGNORE glob expression for files to ignore, when watching for changes
--no-initial skip the initial build
--open-browser open the browser after building documentation
--delay DELAY how long to wait before opening the browser
--watch DIR additional directories to watch
--pre-build COMMAND additional command(s) to run prior to building the documentation
--post-build COMMAND additional command(s) to run after building the documentation
Using with Makefile
-------------------
FYI: Sphinx is planning to `move away from`_ using `Makefile`.
To use sphinx-autobuild with the Makefile generated by Sphinx,
add the following to the end of the Makefile:
.. code-block:: make
livehtml:
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
``make livehtml`` will now invoke sphinx-autobuild.
If you generated the `Makefile` with an older version of sphinx,
this syntax might not work for you.
Consider `updating to the newer structure`_.
.. _move away from: https://github.com/sphinx-doc/sphinx/issues/5618#issuecomment-502415633
.. _updating to the newer structure: https://github.com/sphinx-doc/sphinx/blob/v3.0.0/sphinx/templates/quickstart/Makefile.new_t
Automatically opening the browser
---------------------------------
sphinx-autobuild can open the homepage of the generated documentation
in your default browser.
Passing ``--open-browser`` will enable this behaviour.
Automatically selecting a port
------------------------------
sphinx-autobuild asks the operating system for a free port number
and use that for its server.
Passing ``--port=0`` will enable this behaviour.
Workflow suggestions
====================
Working on a Sphinx HTML theme
------------------------------
When working on a Sphinx HTML theme,
add the source directory of the theme as a watch directory.
It is also recommended to disable Sphinx's incremental builds
by passing the ``-a`` option to sphinx-autobuild.
.. code-block:: bash
sphinx-autobuild -a docs docs/_build/html --watch path/to/theme
This results in slower builds, but it ensures that
all pages are built from the same state of the HTML theme.
It also works around a `known issue in Sphinx `__
which causes significant problems during theme development.
Working on multiple projects
----------------------------
When working on multiple Sphinx documentation projects simultaneously,
it is required to use different output directories for each project.
It is also recommended to use ``--port=0`` and ``--open-browser``
to avoid needing to manually manage ports and opening browser windows
(which can get tedious quickly).
.. code-block:: bash
sphinx-autobuild --port=0 --open-browser pikachu/docs pikachu/docs/_build/html &
sphinx-autobuild --port=0 --open-browser magikarp/docs magickarp/docs/_build/html &
Notifications for build cycles
------------------------------
As an example of using the ``--pre-build`` and ``--post-build`` arguments,
the command below uses `notify-send` to send a notification when a build
starts and finishes.
.. code-block:: bash
sphinx-autobuild docs d
## Recent releases
| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `2025.8.25` | 2026-04-21 | Low | Imported from PyPI (2025.8.25) |
| `2025.08.25` | 2025-08-25 | Low | 2025.08.25 |
| `2025.08.25` | 2025-08-25 | Low | 2025.08.25 |
| `2025.08.25` | 2025-08-25 | Low | 2025.08.25 |
| `2025.08.25` | 2025-08-25 | Low | 2025.08.25 |
| `2025.08.25` | 2025-08-25 | Low | 2025.08.25 |
| `2025.08.25` | 2025-08-25 | Low | 2025.08.25 |
| `2025.08.25` | 2025-08-25 | Low | 2025.08.25 |
| `2025.08.25` | 2025-08-25 | Low | 2025.08.25 |
| `2025.08.25` | 2025-08-25 | Low | 2025.08.25 |
## Citation
- HTML: https://www.freshcrate.ai/projects/sphinx-autobuild
- Markdown: https://www.freshcrate.ai/projects/sphinx-autobuild.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/sphinx-autobuild/deps
_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._