# Furo: a minimal Sphinx theme for documentation sets that are not enormous

> Furo is a Sphinx HTML theme distributed on PyPI under the MIT licence. It replaces the default Alabaster look with a three-column layout, and it is deliberately biased toward smaller docsets rather than thousand-page manuals.

**pradyunsg/furo** — A clean customizable documentation theme for Sphinx

- Repository: https://github.com/pradyunsg/furo
- Website: https://pradyunsg.me/furo/quickstart
- Stars: 3,602 · Forks: 393
- Language: Sass
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/pradyunsg-furo

## The problem Furo solves: Sphinx ships with a theme nobody chose

Sphinx generates HTML, but the theme it ships with is a default rather than a design decision. Projects that care about how their documentation reads end up either writing CSS against that default or moving to a different generator entirely. Furo occupies the space in between: it is a drop-in theme for an existing Sphinx project, so the reStructuredText and Markdown sources, the extension configuration and the build pipeline all stay where they are.

The audience is narrow and identifiable. The README lists urllib3, attrs, pip, the Python Developer's Guide, Blender and black as users. Those are library and tool documentation sets, not multi-thousand-page product manuals. Furo's own elevator pitch says it is "biased for smaller docsets", where showing the whole hierarchy in the sidebar does not overwhelm the reader. That sentence is the honest boundary of the project, and it is worth taking literally rather than treating as marketing modesty.

What you get for the change is a three-column layout, a sidebar that carries navigation and inter-page links, and typography that the project describes as clear. None of that is novel in 2026. The reason to pick Furo over hand-rolled CSS is that the styling work is already done and someone else maintains it.

## How Furo is built: Jinja templates, Sass, and sphinx-basic-ng underneath

Furo is not a standalone theme engine. It depends on sphinx-basic-ng, which provides the base Jinja template structure, and Furo layers its own templates and styles on top. The Python package declares beautifulsoup4, sphinx-basic-ng, pygments and accessible-pygments as runtime dependencies, so HTML post-processing and syntax highlighting come from those rather than from code inside Furo.

The stylesheet pipeline is separate from the Python package. The repository root holds package.json, webpack.config.js and postcss.config.js, and the npm build script is simply webpack. Sass is the primary language of the repository, and the devDependencies list sass, sass-loader, postcss-loader, autoprefixer, css-loader and css-minimizer-webpack-plugin. In other words, the CSS a reader downloads is compiled and minified ahead of time, not assembled in the browser.

Building a release goes through sphinx-theme-builder rather than setuptools. The build-system table in pyproject.toml requires sphinx-theme-builder >= 0.2.0a10 and sets the build backend to sphinx_theme_builder. That same table pins node-version to 18.20.5 and names styles/furo-extensions.css as an additional compiled static asset. The practical consequence for anyone packaging Furo is that a Node toolchain is part of the release process, not an optional extra.

The theme registers itself through an entry point: the sphinx.html_themes group maps furo to the furo module. That is why setting html_theme to the string "furo" is enough for Sphinx to find it once the package is installed.

## Installing Furo and switching a Sphinx project over

Furo is distributed on PyPI, and the README gives a three-step quickstart. The first step is installing the theme into the same environment that builds your documentation, not into your application's runtime environment.

```bash
pip install furo
```

After that command the furo package is importable and its Sphinx entry point is registered. Nothing else in the project changes at this point; your existing HTML output is still generated with whatever theme was configured before.

The second step is a single line in conf.py. The README shows exactly this assignment:

```python
html_theme = "furo"
```

On the next build, Sphinx resolves that name through the sphinx.html_themes entry point and uses Furo's templates. The README's third step is simply the observation that the generated HTML pages now use the theme. If you preview the build output, the visible change is the three-column layout: navigation on one side, content in the middle, and page-level links alongside it.

The declared Python requirement is 3.8 or newer, and the Sphinx requirement is at least 7.0 but below 10.0. A project still pinned to Sphinx 6 or earlier cannot install this version of Furo without also moving Sphinx forward, which is a bigger change than a theme swap.

## What Furo deliberately does not do

The bias toward smaller docsets is the limitation that matters most, and it comes from the project's own description rather than from a bug report. A theme that renders the entire navigation hierarchy in a sidebar works when that hierarchy is a few levels deep. Point it at a documentation set with dozens of top-level sections and hundreds of pages and the sidebar becomes the dominant element on the page. Furo does not claim to solve that; it says it is intended for the case where it is not a problem.

The theme is also opinionated about restraint. Its stated goal is that the content matters more than the scaffolding around it. If you want a documentation site with a marketing landing page, a large hero image, versioned dropdowns built into the chrome, or a search experience that ranks results by relevance across multiple projects, Furo is the wrong layer. It styles Sphinx's output; it does not replace Sphinx's search index, which is built by Sphinx itself.

There is a build-side constraint too. Because the release pipeline depends on sphinx-theme-builder and a pinned Node version, anyone forking Furo to change the Sass has to reproduce that toolchain. Editing the compiled CSS in a downstream project is possible, but it puts you outside the path the project maintains.

Finally, the dependency floor is real. Furo requires Sphinx 7.0 or later. On an older documentation build, installing Furo means upgrading Sphinx, and that upgrade can break extensions that have not caught up.

## Furo compared with mkdocs-material

The README names mkdocs-material as one of the themes Furo borrowed elements from, alongside Just the Docs, GitBook and pdoc3. The difference between the two is not visual style; it is the generator underneath.

mkdocs-material is a theme for MkDocs, which takes Markdown files and a YAML configuration file. Furo is a theme for Sphinx, which takes reStructuredText or Markdown through MyST and a Python configuration file, and which brings a large extension ecosystem for autodoc, intersphinx and cross-references. Choosing between them is mostly a question of which generator your project already uses. If your API documentation is generated from Python docstrings by autodoc, moving to MkDocs means replacing that machinery, not just the stylesheet.

Within Sphinx itself, the alternative to Furo is the default theme or one of the other themes in the ecosystem. Staying on the default costs nothing and requires no new dependency; the trade-off is that you get Sphinx's stock appearance. Furo's value is that it changes that appearance with one configuration line and no template work, at the price of one more package in the documentation build environment.

## Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-21. Releases are date-versioned rather than semantic: 2025.12.19, 2025.09.25 and 2025.07.19 are the recent ones listed. That scheme tells you when a release happened but not what kind of change it contains, so a version bump alone does not signal whether the upgrade is safe.

The README describes Furo as a volunteer maintained open source project. There is no commercial support tier mentioned, and no long-term support branch is documented. Upgrading means installing a newer wheel and rebuilding; the README does not document a rollback procedure, so pinning a known-good version in your documentation requirements is the practical way to keep the option open.

The licence is MIT, declared in pyproject.toml as a file reference to LICENSE and classified as OSI Approved :: MIT License. MIT is permissive: you can use the theme in a commercial documentation build and modify it. The one obligation that travels with it is retaining the copyright notice and permission text. Note that Furo's dependencies carry their own licences, and those are separate from Furo's. This is a description of what the files say, not legal advice; if licence compatibility matters for your distribution, read the LICENSE file and the dependency metadata yourself.

## Conclusion

Adopt Furo if your Sphinx project is a library manual or API reference of modest size and you want a readable default without writing CSS. Do not adopt it if your sidebar hierarchy would run to dozens of nested entries, since the README states the theme is biased for smaller docsets. Before switching, check that your Sphinx version falls inside the declared range of 7.0 up to but excluding 10.0, then set html_theme = "furo" in conf.py and rebuild to confirm your custom templates and static assets still resolve.

## FAQ

### How do I install the Furo Sphinx theme?

The README's quickstart says to install it into your documentation build environment with pip install furo, then set html_theme = "furo" in conf.py. The next build produces HTML using the theme.

### Which Sphinx versions does Furo support?

The project metadata declares sphinx >= 7.0,<10.0, so Sphinx 7.0 and later are supported but Sphinx 10 and above are excluded. The declared Python requirement is 3.8 or newer.

### Is Furo suitable for very large documentation sets?

The README states that Furo is biased for smaller docsets, where presenting the entire hierarchy in the sidebar is not overwhelming. For a documentation set with a very deep or very wide navigation tree, that sidebar becomes the dominant element on the page.

### What licence is Furo released under?

Furo is licensed under the MIT License, declared in pyproject.toml and classified as OSI Approved :: MIT License. Its dependencies carry their own separate licences.

## Sources

- [License: MIT](https://github.com/pradyunsg/furo/blob/main/LICENSE)
- [pradyunsg/furo on GitHub](https://github.com/pradyunsg/furo)
- [Project website](https://pradyunsg.me/furo/quickstart)
- [README](https://github.com/pradyunsg/furo/blob/main/README.md)
- [Releases](https://github.com/pradyunsg/furo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pradyunsg-furo