Python Docs Theme

2026.3 · active · verified Thu Apr 16

The Sphinx theme for the CPython docs and related projects. It provides a clean, responsive design and includes features like a dark mode, code copy buttons, and internationalization support. The library is actively maintained with frequent releases, typically on a monthly or bi-monthly cadence. The current version is 2026.3.

Common errors

```
Theme error: no theme named 'python_docs_theme' found (missing theme.conf?)
```
cause The `python-docs-theme` package is either not installed in the Sphinx build environment or `html_theme` is misspelled in `conf.py`.

fix Ensure the theme is installed with `pip install python-docs-theme` and that `html_theme = 'python_docs_theme'` is correctly set in your `conf.py` file.
```
ValueError: The 'python-docs-theme' requires Python 3.12 or newer.
```
cause Attempting to build documentation with `python-docs-theme` version 2025.4 or newer using a Python interpreter older than 3.12.

fix Upgrade your Python environment to 3.12 or a later version, or if unable to upgrade, pin the theme version to `python-docs-theme<2025.4`.
```
Theme error: The 'python-docs-theme' requires Sphinx 7.3 or newer.
```
cause Attempting to build documentation with `python-docs-theme` version 2025.4 or newer using a Sphinx version older than 7.3.

fix Upgrade your Sphinx installation to 7.3 or a later version using `pip install -U Sphinx`, or if unable to upgrade, pin the theme version to `python-docs-theme<2025.4`.

Warnings

breaking Version 2025.4 and newer dropped support for Python 3.10 and 3.11.
Fix: Upgrade your Python environment to 3.12 or newer, or pin `python-docs-theme<2025.4`.
breaking Version 2025.4 and newer requires Sphinx 7.3 or newer.
Fix: Upgrade your Sphinx installation to 7.3 or newer, or pin `python-docs-theme<2025.4`.
gotcha The behavior of code block copy buttons was enhanced across versions. Initially, they appeared on hover/click (2025.5), then specifically enabled for shell sessions and consoles (2026.2).
Fix: Upgrade to `python-docs-theme` 2026.2 or newer to ensure full copy button functionality for all code blocks, including shell and console examples.
gotcha Custom configurations for `html_sidebars`, `html_theme_path`, or `html_theme_config` in `conf.py` can interfere with the theme's default layout and features.
Fix: If encountering unexpected layout issues, temporarily comment out or unset these theme-related configurations in `conf.py` to see if they are causing the conflict.

Install

pip install python-docs-theme Install latest version

Imports

html_theme
```
html_theme = 'python_docs_theme'
```
This setting is placed in your Sphinx project's conf.py file to activate the theme.

Quickstart

A basic Sphinx project setup, demonstrating how to enable the `python-docs-theme`. After running `sphinx-quickstart` to create your project structure, edit `conf.py` to set the `html_theme`.

mkdir my_docs
cd my_docs
sphinx-quickstart  # Follow prompts, choose 'y' for separate source/build, 'y' for autodoc

# Edit source/conf.py (or conf.py directly if not using separate source/build)
# Add or modify the following line:
# html_theme = 'python_docs_theme'

# Create a simple reStructuredText file (e.g., source/index.rst)
# .. toctree::
#    :maxdepth: 2
#    :caption: Contents:
#
#    intro

# Create source/intro.rst
# My First Page
# ============
#
# Hello, world! This is my first page using the Python Docs Theme.

make html  # or sphinx-build -b html source build

view raw JSON →