sphinx "WARNING: download file not found" download role error
Fixes Sphinx download-role warnings when the linked file cannot be found at build time. Use when the log shows download file not found for a :download: role. Not for image or toctree warnings.
TL;DR
Place the downloadable file inside the source directory and reference it with a path relative to the document, spelled exactly. The download role only finds files that live under the source tree.
Error
WARNING: download file not found: specs/api-v2.yamlSteps
- Find the
:download:role in the source and note the path it references. Expected: you have the exact string Sphinx tried to resolve. - Check the file exists under the source directory at that relative path, resolved from the referencing document's folder. Expected:
lsconfirms the file is present or shows it is missing. - If the file lives outside the source tree (e.g. in a build output folder), copy or symlink the source artifact into the docs source tree, or generate it there as a build step. Expected: the file is inside the source directory before Sphinx runs.
- Rebuild and verify the download link appears on the page and the warning is gone. Expected: zero download warnings and a working link.
When to use
- The
:download:role warns that its file was not found - Downloadable artifacts (specs, schemas, sample configs) are generated by another build step
- Docs were reorganized and relative download paths broke
When not to use
- The link should point at an external URL (use a plain hyperlink, not the download role)
- The file exists but the link text is wrong (cosmetic, not this warning)
- You want the file served from a CDN instead of bundled with the docs
Tool compatibility
Sphinx 5.x through 8.x, all builders. The HTML builder copies the file into the output; the link breaks if the file is absent.
Variant phrasings
download role points at a generated OpenAPI file
Generate the spec into the source tree as a pre-build step (tox, make, or CI script) so the file exists when Sphinx runs.
download works locally but warns in CI
The file is likely gitignored or produced by a local-only step. Commit a checked-in copy or replicate the generation step in CI.
Why it happens
The download role resolves its argument against the source directory at build time and refuses to reach outside it for security. Generated artifacts usually land in build or dist folders, so the reference dangles until the generation step writes into the source tree.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_yFm2vYsr6GkkOIRQGMerMA