Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.5s · import 0.000s · 93MB
94MB installed
● package 94MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
notfound.extension
✓ extensions = ['notfound.extension']
Add 'notfound.extension' to the list of Sphinx extensions in your conf.py file.
To quickly enable `sphinx-notfound-page`, install it via pip and then add `'notfound.extension'` to the `extensions` list in your Sphinx `conf.py` file. For custom content, you can define `notfound_context` directly in `conf.py` or create a `404.rst` file and set `notfound_template = '404.rst'`. Remember to add `:orphan:` to the top of any custom `404.rst` file to prevent Sphinx warnings.
# conf.py
# Existing extensions list
extensions = [
# ... other extensions
'notfound.extension',
]
# Optional: Customize 404 page content directly in conf.py
notfound_context = {
'title': 'Page Not Found',
'body': '<h1>Oops! This page does not exist.</h1>\n\n<p>Please check the URL or navigate from the <a href="/">homepage</a>.</p>',
}
# Optional: Use a custom 404.rst file for content
# notfound_template = '404.rst'
# If using a custom 404.rst, ensure it has the :orphan: metadata
# Example 404.rst content (place next to conf.py):
# :orphan:
#
# Error 404: Page Not Found
# =========================
#
# The page you are looking for does not exist. Please check the URL.
Debug
Known issues
gotchaWhen testing locally by opening `404.html` directly (e.g., via `file://` in a browser), assets like CSS and JavaScript may appear broken. This is expected behavior because the extension generates absolute URLs, which require a web server to resolve correctly.fixDeploy your documentation to a web server (e.g., Read the Docs, GitHub Pages) or serve it locally using a proper HTTP server (not just `file://`).
affects: All versions
gotchaSimple local web servers (like Python's `http.server`) often do not have a default handler for 404 error codes. This means they may not serve the generated `404.html` when a page is truly not found. For production deployments, your web server (e.g., Nginx, Apache) must be configured to handle 404 errors by serving the generated `404.html` with a 404 HTTP status code.fixConfigure your web server's error handling. For Nginx, use `error_page 404 /404.html;`. For Apache, use `ErrorDocument 404 /404.html`. Ensure the server returns an actual 404 HTTP status code, not a 'soft 404' (200 OK with a 'not found' message).
affects: All versions
gotchaThe `notfound_urls_prefix` configuration option (used for hosting on GitHub Pages, sub-projects on Read the Docs, etc.) *must* start and end with a `/` if it's a string, unless it is set to `None`. Failure to do so can lead to incorrect asset paths and broken 404 pages.fixAlways ensure `notfound_urls_prefix` is correctly formatted, for example: `notfound_urls_prefix = '/my_repo/'` for GitHub Pages, or `notfound_urls_prefix = None` for single-version Read the Docs projects.
affects: All versions
breakingSphinx 7.2.x introduced API changes (e.g., use of `pathlib.Path` objects instead of strings for paths, changes to the `toctree` adapter) which caused compatibility issues with `sphinx-notfound-page` (and other Sphinx extensions/themes) that relied on the previous API.fixEnsure you are using a version of `sphinx-notfound-page` that is compatible with your Sphinx version. For earlier issues, users often had to temporarily pin Sphinx to `<7.2` until the extension was updated. Version 1.1.0 should be compatible with recent Sphinx releases.
affects: Sphinx 7.2.0 (and potentially early 7.2.x releases)
gotchaIf you create a custom `404.rst` file to define your 404 page content, Sphinx may issue a warning that the document is not included in any `toctree`.fixAdd `:orphan:` metadata as the very first line in your `404.rst` file to suppress this warning. Example: `:orphan:
My 404 Page`.
affects: All versions
Upgrade
Version history
1.1.0latest on PyPI · released Jan 28, 2025
Audit
Dependencies
SphinxrequiredThis is a Sphinx extension and requires Sphinx to build documentation.