Read the Docs Sphinx Theme

3.1.0 · active · verified Sun Apr 05

The `sphinx-rtd-theme` is the official Sphinx theme for Read the Docs, designed to provide an excellent reading experience for documentation users on both desktop and mobile devices. It is widely adopted across many open-source projects. The current version is 3.1.0, and it maintains an active development and release cadence.

Warnings

breaking Version 3.1.0 (and 2.0.0 onwards) drops support for Sphinx versions older than 6.0. Projects using older Sphinx versions will need to upgrade Sphinx or pin an older `sphinx-rtd-theme` version. Similarly, Python versions older than 3.8 are no longer supported.
Fix: Upgrade Sphinx to 6.0 or newer and Python to 3.8 or newer. If not possible, pin `sphinx-rtd-theme<2.0.0` or `sphinx-rtd-theme<3.1.0` depending on your Sphinx/Python versions.
breaking The HTML4 writer is officially deprecated since version 2.0.0 and will throw an error if still configured.
Fix: Ensure your Sphinx project uses the HTML5 writer. Modern Sphinx versions use HTML5 by default.
deprecated The `analytics_id` and `analytics_anonymize_ip` configuration options are deprecated in version 3.1.0. Users should migrate to `sphinxcontrib-googleanalytics` for Google Analytics integration.
Fix: Remove `analytics_id` and `analytics_anonymize_ip` from `conf.py` and configure `sphinxcontrib-googleanalytics` instead.
deprecated Defining `html_theme_path` will raise a warning in newer versions of the theme, as it's no longer required for local installations. `extra_css_files` is also deprecated and will be removed in a future version.
Fix: Remove `html_theme_path` from `conf.py` if it points to the installed theme. Migrate custom CSS to be included differently as per theme documentation.
gotcha For search, smooth scrolling, and the flyout menu to function correctly, `sphinx_rtd_theme` must be explicitly declared in the `extensions` list in `conf.py`. This ensures `sphinxcontrib-jquery` is activated.
Fix: Add `'sphinx_rtd_theme'` to your `extensions` list in `conf.py`.
gotcha Errors during documentation builds with a new theme are often due to conflicting theme-specific configurations such as `html_sidebars`, `html_theme_path`, or `html_theme_config`.
Fix: If encountering build errors after switching themes, try unsetting `html_sidebars`, `html_theme_path`, or `html_theme_config` in your `conf.py`.

Install

pip install sphinx-rtd-theme Install `sphinx-rtd-theme`

Imports

html_theme
```
html_theme = "sphinx_rtd_theme"
```
This setting should be placed in your Sphinx project's conf.py file to activate the theme.

Quickstart

After installing the theme, update your Sphinx project's `conf.py` file to specify `sphinx_rtd_theme` as the `html_theme` and add `sphinx_rtd_theme` to your `extensions` list. Then, build your Sphinx documentation.

# First, create a Sphinx project if you don't have one:
# sphinx-quickstart

# In your project's conf.py file:
# ------------------------------
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

project = 'My Awesome Project'
copyright = '2026, Your Name'
author = 'Your Name'
release = '0.1.0'

extensions = [
    'sphinx_rtd_theme'
]

html_theme = "sphinx_rtd_theme"

# To build the documentation (run from your project root):
# -------------------------------------------------------
# make html
# or
# sphinx-build -b html . _build

view raw JSON →