Registry / web-framework / sphinx-rtd-theme

sphinx-rtd-theme

library3.1.0pypypi✓ verified 25d ago

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.

web-framework

pip install sphinx-rtd-theme

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPHINX-RTD-THEME

sphinx-rtd-theme

web-frameworkpythonv3.1.0

Install

5.6s avg

Import

—

Disk

105MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 102.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 5.6s · import 0.000s · 103MB

105MB installed

● package 105MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

html_theme

✓ html_theme = "sphinx_rtd_theme"

This setting should be placed in your Sphinx project's conf.py file to activate the theme.

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

Debug

Known issues

breakingVersion 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.

affects: >=2.0.0

breakingThe 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.

affects: >=2.0.0

deprecatedThe `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.

affects: >=3.1.0

deprecatedDefining `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.

affects: >=3.1.0

gotchaFor 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`.

affects: All versions

gotchaErrors 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`.

affects: All versions

Upgrade

Version history

3.1.0latest on PyPI · released Jan 12, 2026

Audit

Dependencies

SphinxrequiredRequired for building documentation. Version 3.1.0 of sphinx-rtd-theme supports Sphinx >=6.0.

docutilsrequiredCore dependency for reStructuredText parsing in Sphinx. Version constraints align with supported Sphinx versions.

sphinxcontrib-jqueryrequiredRequired for interactive features like search, smooth scrolling, and the flyout menu when using the theme as an extension.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/readthedocs/sphinx_rtd_theme ↗

packagehttps://pypi.org/project/sphinx-rtd-theme/ ↗

homepagehttps://sphinx-rtd-theme.readthedocs.io/ ↗