Skip to content

Conversation

@ianhi
Copy link

@ianhi ianhi commented Oct 17, 2025

Current Behavior

Default sphinx-autobuild ... will open port 8000, and if that's already occupied it will fail with an error

The HTML pages are in build/html.
[sphinx-autobuild] Serving on http://127.0.0.1:8000
[sphinx-autobuild] Waiting to detect changes...
ERROR:    [Errno 48] error while attempting to bind on address ('127.0.0.1', 8000): [errno 48] address already in use
make: *** [watch] Error 1

This PR

Still defaults to port 8000. But if that port is occupied then fall back to auto detecting a port. I tihnk this makes for a better user experience and is what most users will want. It also mimics the common behavior in the npm ecosystem. But it's sitll possible to request a specific port and have it fail

[sphinx-autobuild] Port 8000 already in use. Attempting to find a free port...
[sphinx-autobuild] Using port 50268 instead.
[sphinx-autobuild] Starting initial build
[sphinx-autobuild] > python -m sphinx build docs docs/_build/html
Running Sphinx v8.2.3
....
The HTML pages are in docs/_build/html.
[sphinx-autobuild] Serving on http://127.0.0.1:50268
[sphinx-autobuild] Waiting to detect changes...

You can still specify a port and have it fail if occupied

➜  sphinx-autobuild git:(auto-ports) ✗ uv run sphinx_autobuild docs docs/_build/html --port 8000
[sphinx-autobuild] Error: Cannot bind to 127.0.0.1:8000. The port is already in use. Use --port 0 to automatically find a free port.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant