PyData Sphinx Theme

0.17.0 · active · verified Fri Apr 10

The PyData Sphinx Theme is a clean, three-column, Bootstrap-based Sphinx theme designed for the PyData community. It provides a modern, responsive design with built-in light/dark mode toggling and extensive customization options via `html_theme_options`. Currently at version 0.17.0, the project maintains a regular release cadence, with new versions published frequently (typically monthly or upon significant feature additions/bug fixes).

Warnings

gotcha New major versions of Sphinx may not be immediately supported. The PyData Sphinx Theme aims to support the latest Sphinx version that is older than 6 months. Using a very recent Sphinx release might lead to build issues until the theme is updated.
Fix: If experiencing issues with a new Sphinx version, try pinning to an older, compatible Sphinx version (e.g., `pip install 'sphinx<6'`) or wait for a theme update. Refer to the theme's official documentation for supported Sphinx versions.
breaking Version 0.16.x introduced significant changes, including an upgrade to Bootstrap 5 and the removal of jQuery. This may break custom CSS, JavaScript, or certain theme options that relied on previous versions of Bootstrap (4) or jQuery.
Fix: Review the theme's changelog for `v0.16.0` and subsequent releases. Update custom CSS and JavaScript to be compatible with Bootstrap 5 and vanilla JavaScript where jQuery was previously used. Some theme options might have been removed or renamed (e.g., `sidebarwidth` was removed in v0.16.1).
gotcha Theme-specific options must be set within the `html_theme_options` dictionary in `conf.py`. Directly defining `html_` variables (e.g., `html_sidebars`, `html_theme_path`, `html_theme_config`) might conflict with or override the theme's internal logic, leading to unexpected layout or functionality.
Fix: Always configure theme-specific settings through the `html_theme_options` dictionary. If you need to deeply customize aspects like sidebars, consult the theme's documentation for the correct approach rather than overriding global Sphinx `html_` variables directly.

Install

pip install pydata-sphinx-theme Install stable version
conda install pydata-sphinx-theme --channel conda-forge Install with Conda

Imports

html_theme configuration
```
html_theme = "pydata_sphinx_theme"
```
The theme is configured in your Sphinx project's `conf.py` file by setting the `html_theme` variable. There are no direct Python imports from the library for typical usage.

Quickstart

To use the PyData Sphinx Theme, set `html_theme = "pydata_sphinx_theme"` in your `conf.py`. All theme-specific customizations are managed through the `html_theme_options` dictionary. This example also shows how to add an icon link and customize the footer.

# conf.py
import os
import sys

project = 'My Awesome Project'
copyright = '2026, My Team'
author = 'My Team'
release = '0.1'

html_theme = "pydata_sphinx_theme"

html_theme_options = {
    "icon_links": [
        {
            "name": "GitHub",
            "url": "https://github.com/my-org/my-project",
            "icon": "fa-brands fa-github",
            "type": "fontawesome",
        }
    ],
    "navbar_persistent": [], # Remove 'search' from persistent navbar
    "show_prev_next": False,
    "switcher": {
        "version_match": "latest",
    },
    "footer_start": ["copyright"],
}

html_static_path = ['_static']
html_css_files = ['custom.css'] # Example for custom CSS

view raw JSON →