pydata-sphinx-theme is a Bootstrap Sphinx theme with a Node build behind it

A community theme for the documentation community

The PyData Sphinx Theme is a clean, three-column, Bootstrap-based Sphinx theme by and for the PyData community.

That description carries the whole design brief. Three columns is a layout decision with consequences: it gives a persistent sidebar for navigation, a content column, and a right-hand column that in this theme carries the version switcher, the edit link and the table of contents. Bootstrap means the visual language comes from a framework the reader may already recognise, and the theme inherits its responsive behaviour and its accessibility work rather than reinventing them.

The distribution channels are the two you would expect for a Python documentation tool. The theme is available on PyPI and on conda-forge, with badges for both in the README, plus a Read the Docs build badge, which tells you the project itself is documented and hosted through the same stack it serves.

The project is BSD-3-Clause licensed, its homepage is the documentation site at pydata-sphinx-theme.readthedocs.io, and the classifier in the package metadata says Development Status 5, Production/Stable with support for Python 3.11 through 3.14.

The audience is documentation teams, and specifically the ones inside the Python scientific ecosystem. The README points at four resources: the documentation, a set of examples, a community and contributing page, and a Transifex project for translation, which is the quiet sign that this is an international project with a translation workflow rather than a single author's styling.

The last push was on 2026-10-19, the repository is not archived, and the recent releases are v0.22.0 on 2026-09-25, v0.23.0rc0 on 2026-09-29 and v0.23.0 on 2026-10-08.

Two install commands and one line of configuration

The installation section is short enough to reproduce, and it is the complete story for a user.

The theme is available on PyPI and conda-forge, and you install it in your documentation build environment:

pip install pydata-sphinx-theme
# or
conda install pydata-sphinx-theme --channel conda-forge

Then, in the conf.py of your Sphinx docs, you update the html_theme configuration option:

html_theme = "pydata_sphinx_theme"

And that's it, as the README puts it. There is no separate asset build for the user, no template directory to point at, and no JavaScript to compile, because the wheel already contains the compiled CSS and JavaScript.

The two channels exist for different reasons. pip is the obvious path for a project that already builds its docs in a virtual environment, and conda-forge is the one that gets the theme and its transitive dependencies into a shared environment alongside the rest of the scientific Python stack, which is where a lot of documentation builds live.

The theme name in conf.py, pydata_sphinx_theme, uses an underscore character, while the distribution name and the pip package use hyphens, pydata-sphinx-theme. That difference is a small trap that catches people, since the value of html_theme is a Python importable module name rather than the package name.

The Sphinx version caveat is the thing to plan around

There is one note in the README that deserves more attention than it gets, and it is about timing.

The theme may not work with the latest major versions of Sphinx, especially if they have only recently been released. Please give us a few months of time to work out any bugs and changes when new releases are made. The README links to the contributing documentation for supported Sphinx versions for more information.

This is a deliberate policy rather than neglect, and the package metadata explains the mechanism. The theme requires sphinx>=8.2,<10, so the upper bound is declared rather than left to chance, and the fact that the classifiers list Python 3.11 to 3.14 shows the same care about the other side of the dependency.

For most documentation teams this is a non-issue, because a docs build is pinned anyway and a project rebuilds its docs on its own schedule rather than on the day Sphinx ships. For a team whose documentation is built in a continuous integration job that always installs the latest Sphinx, the note is the difference between a green build and a red one, and the supported versions page is the page to read before you upgrade.

The optional dependencies make the same point in a different direction. The doc extra pins several things tightly, including astroid with an exclusion for 4.0.3 and a comment about it being a fix for sphinx.autoapi, sphinx-sitemap held below 2.7.0 with a TODO comment about unpinning it once a solution is offered, and sphinx-autoapi at an exact version. A theme that pins its own tooling is a theme that takes documentation build breakage seriously.

The Python package is a front for a Node and webpack build

The repository layout shows that this is not a pure Python project, and the packaging says so explicitly.

The build system requires sphinx-theme-builder>=0.3.2 with the sphinx_theme_builder backend, and the theme configuration names a node-version of 24.21.0. The package.json is a normal modern JavaScript build: webpack with webpack-cli, sass and sass-loader, css-minimizer-webpack-plugin, mini-css-extract-plugin, html-webpack-plugin, terser-webpack-plugin and css-loader.

The scripts are the ones you would expect. build runs webpack in production mode, build-dev runs it in development mode, and profile produces a bundle-stats.json that view-profile then opens in the bundle analyzer. There is a prettier script for TypeScript, JavaScript, CSS, SCSS, JSON and Markdown, and a stylelint script for the SCSS in src, with a separate check command for CI.

The runtime dependencies are small and recognisable. Bootstrap 5.2.2 supplies the framework, @fortawesome/fontawesome-free the icons, @popperjs/core the popover behaviour Bootstrap needs, compare-versions a version comparison helper, and webpack-bundle-analyzer the profiling tool.

So the picture is a theme whose Python distribution is assembled from a JavaScript bundle. That is the standard shape for a Sphinx theme that wants modern CSS tooling, and it is also why the theme ships precompiled assets: the Node toolchain is a development dependency, not something a documentation user has to install.

Compiled assets and translations are packaged into the wheel

The theme configuration lists the additional compiled static assets that go into the distribution, and the list explains several things about how the theme is put together.

The assets are webpack-macros.html, the vendor directory, scripts/bootstrap.js, scripts/fontawesome.js, and the locale directory. Two of those are immediately explanatory. The vendor directory is the bundled third-party JavaScript, and scripts/bootstrap.js and scripts/fontawesome.js are the entry points that load the Bootstrap and Font Awesome code into a Sphinx page, which is how a Sphinx theme imports a JavaScript library that has no native Sphinx equivalent.

The locale directory is the translation output, and it links directly to the rest of the packaging story. The repository has a babel.cfg at the root and a .transifex.yaml, and the README points at a Transifex project for translation. Translation is not an afterthought added later; the compiled locales are part of what the build produces and part of what the wheel contains.

The last thing the repository listing shows is how much of the tooling lives in the project rather than in a user's setup: a .prettierignore and a .stylelintrc.yaml for the CSS and JavaScript, a .pre-commit-config.yaml so the formatting rules are enforced before a commit lands, a .devcontainer directory for a reproducible development environment, tox.ini for the Python side, a .readthedocs.yaml for the documentation build, a package-lock.json for the Node side, and a webpack.config.js at the root.

The RELEASE.md file at the root and a dedicated docs directory tell you that releasing and documenting are part of the project's regular work rather than an afterthought.

Where the PyData Sphinx Theme is the wrong tool

The limits are clear and they are mostly about scope.

First, it is a Sphinx theme, so it does nothing for MkDocs, Docusaurus, VitePress, or a documentation generator written in something else entirely. If your documentation stack is not Sphinx, this is a non-starter regardless of how good the theme looks.

Second, the three-column layout is the theme's identity, and it is a cost on narrow screens and in embedded contexts. A site that wants a single wide column for long code listings or for embedding in another page has to fight the layout, and the theme offers no documented mode that abandons the three-column structure.

Third, the toolchain is heavier than the two install commands suggest. For a user it is fine, because the wheel is self-contained. For a contributor it is a Python project, a Node project and a Sass and webpack pipeline, with prettier, stylelint, axe-core for accessibility testing in the dev dependencies, plus tox for the Python side. The theme is maintained by a small group of people, and the maintainer listed in the package metadata is Joris Van den Bossche.

Fourth, the Sphinx version policy means you will occasionally be stuck. When a new Sphinx major lands, the theme may not support it for a few months, and a team that always installs the latest Sphinx has to pin an older one in the meantime. The upper bound of sphinx>=8.2,<10 in the metadata is the tool that prevents a silent break, but it is also a ceiling you will hit.

Fifth, the Bootstrap dependency is a long-term commitment. It is what makes the theme look the way it does and what gives it the responsive and accessible behaviour, but it also means the theme follows Bootstrap's release line as well as Sphinx's, and a Bootstrap major upgrade is a piece of work the maintainers have to absorb.

Editorial conclusion

Documentation teams in the Python and data science world that want a readable, multi-column Sphinx site with light and dark modes should adopt pydata-sphinx-theme, because it is maintained by the community whose documentation it serves and it installs in two commands. It is the wrong tool outside Sphinx, and the wrong tool when you need to be on a brand new Sphinx major the day it ships, since the project asks for a few months to work out bugs and changes. Before adopting, read the supported Sphinx versions page and check the upper bound, currently sphinx>=8.2,<10, because a Sphinx upgrade past that range is where the friction will be.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. pydata/pydata-sphinx-theme on GitHub
4. README
5. Releases