Sphinx RTD Dark Mode

Common errors

• ModuleNotFoundError: No module named 'sphinx_rtd_dark_mode'

  cause The package `sphinx-rtd-dark-mode` was not installed or installed in a different Python environment.
  fix Run `pip install sphinx-rtd-dark-mode` in the correct Python environment. If using `venv`, ensure it's activated.

• Sphinx build completes, but dark mode toggle or styling is missing/broken.

  cause The extension might not be correctly added to `conf.py`'s `extensions` list, or an old version with static file inclusion bugs is being used. Alternatively, `html_theme` might be set to a non-RTD theme, leading to unexpected behavior (though the extension attempts to correct this).
  fix 1. Verify `'sphinx_rtd_dark_mode'` is in the `extensions` list in `conf.py`. 2. Ensure `html_theme = 'sphinx_rtd_theme'`. 3. Upgrade to the latest version: `pip install --upgrade sphinx-rtd-dark-mode`.

• Some text elements (e.g., function names, admonitions, inline code) are unreadable in dark mode (dark text on dark background).

  cause This is a known bug in older versions of the extension where specific element styles were not correctly converted for dark mode.
  fix Upgrade to the latest version (1.3.0+) of `sphinx-rtd-dark-mode` which includes fixes for these styling issues: `pip install --upgrade sphinx-rtd-dark-mode`.

Warnings

• gotcha This extension is exclusively designed for the 'sphinx_rtd_theme'. If you have a different `html_theme` set in `conf.py`, the extension will override it to `sphinx_rtd_theme` to function correctly.
  Fix: Ensure `html_theme = 'sphinx_rtd_theme'` is set, or be aware the extension will set it for you.
• gotcha The `default_dark_mode` configuration option (boolean) controls whether users see dark mode or light mode on their *first* visit to the documentation. If not explicitly set, the default is `True` (dark mode first). User preferences are stored in local storage thereafter.
  Fix: Set `default_dark_mode = False` in `conf.py` if you prefer users to start in light mode.
• breaking Older versions (prior to 1.0.1 and 1.1.1) had issues with static CSS files not being included during installation, leading to the dark mode not appearing or being partially broken.
  Fix: Upgrade to version 1.1.1 or later (`pip install --upgrade sphinx-rtd-dark-mode`).
• gotcha Various styling issues, such as unreadable text on certain elements (e.g., `guilabel`, admonitions, code blocks, navigation, tables) or incorrect fonts, were present in older versions.
  Fix: Ensure you are using the latest version (1.3.0+) for the most comprehensive styling fixes: `pip install --upgrade sphinx-rtd-dark-mode`.

Install

• pip install sphinx-rtd-dark-mode Install from PyPI

Imports

• sphinx_rtd_dark_mode
  wrong:

  import sphinx_rtd_dark_mode

  correct:

  extensions = ['sphinx_rtd_dark_mode']

  Sphinx extensions are activated by adding their module name to the 'extensions' list in conf.py, not via direct Python imports.

Quickstart

To enable sphinx-rtd-dark-mode, first ensure you have `sphinx` and `sphinx-rtd-theme` installed. Then, add `'sphinx_rtd_dark_mode'` to the `extensions` list in your `conf.py` file. Optionally, set `default_dark_mode = False` if you prefer the light theme on the first load.

# conf.py

import os
import sys
# Add your project's path if necessary
# sys.path.insert(0, os.path.abspath('.'))

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

html_theme = 'sphinx_rtd_theme'
extensions = [
    'sphinx_rtd_dark_mode',
]

# Optional: Set the default mode (True for dark, False for light)
default_dark_mode = True

# To build:
# sphinx-build -b html . _build