404 Not Found pages

If you want your project to use a custom or branded 404 Not Found page, you can put a 404.html or 404/index.html at the top level of your project’s HTML output.

How it works

When our servers return a 404 Not Found error, we check if there is a 404.html or 404/index.html in the root of your project’s output.

The following locations are checked, in order:

  • /404.html or 404/index.html in the current documentation version.

  • /404.html or 404/index.html in the default documentation version.

Tool integration

Documentation tools will have different ways of generating a 404.html or 404/index.html file. We have examples for some of the most popular tools below.

We recommend the sphinx-notfound-page extension, which Read the Docs maintains. It automatically creates a 404.html page for your documentation, matching the theme of your project. See its documentation for how to install and customize it.

If you want to create a custom 404.html, Sphinx uses html_extra_path option to add static files to the output. You need to create a 404.html file and put it under the path defined in html_extra_path.

If you are using the DirHTML builder, no further steps are required. Sphinx will automatically apply the <page-name>/index.html folder structure to your 404 page: 404/index.html. Read the Docs also detects 404 pages named this way.