sphinx-build -b linkcheck: Find Broken Links
sphinx-build -b linkcheck requests every hyperlink in the docs and exits non-zero when a link is broken.
Docs rot when the sites they link to move. The linkcheck builder turns that into a testable gate you can run on a schedule instead of shipping dead links.
What it does
The linkcheck builder visits every external link and anchor, following redirects, and writes an output.txt and output.json report classifying each as ok, redirected, broken, or ignored. It exits non-zero if any link is broken.
Common usage
sphinx-build -b linkcheck docs docs/_build/linkcheck
# then inspect the report
cat docs/_build/linkcheck/output.txtOptions
| Setting (conf.py) | What it does |
|---|---|
| linkcheck_ignore | List of regex URL patterns to skip |
| linkcheck_timeout | Per-request timeout in seconds |
| linkcheck_retries | How many times to retry a failing link |
| linkcheck_anchors | Whether to verify #anchor fragments |
| linkcheck_workers | Number of concurrent request workers |
In CI
Run linkcheck in a separate scheduled job, not on every push, since flaky external hosts cause false failures. Put known-flaky or auth-gated URLs in linkcheck_ignore. Raise linkcheck_retries to smooth over transient network blips on shared runners.
Common errors in CI
A line like (line 12) broken https://example.com/gone - 404 Client Error: Not Found marks a dead link. Anchor 'section' not found appears when linkcheck_anchors is on and a #fragment no longer exists. TimeoutError or Max retries exceeded usually means a slow host, not a real breakage; add it to linkcheck_ignore or raise the timeout.