Furo is a Sphinx documentation theme written by Pradyun Gedam. It provides automatic light and dark mode, a responsive layout, and built-in search, with minimal configuration. Furo is a drop-in replacement for Sphinx's default `alabaster` theme and is the theme used by pip's documentation, attrs, the Black formatter, and many other small-to-medium Python projects.

How do I use Furo with Sphinx?

Install Furo with `uv add --group docs furo` or `pip install furo`, then set `html_theme = "furo"` in `docs/source/conf.py`. No further configuration is required; Furo provides sensible defaults out of the box. Customisation (colors, sidebar links, announcement banner) goes under `html_theme_options` in the same file.

How is Furo different from the Read the Docs theme?

Furo and the Read the Docs theme (`sphinx_rtd_theme`) are both popular replacements for Sphinx's default theme. Furo has built-in light and dark modes and a sidebar suited to projects with shallow navigation. The Read the Docs theme has been around longer and is optimized for projects with deep, multi-level navigation. Choice between them is largely aesthetic.

Is Furo only for Sphinx?

Yes. Furo is a Sphinx-specific theme and does not work with [MkDocs]({{ }}) or other documentation generators. The closest MkDocs equivalent in spirit (clean, modern, light/dark mode) is [Material for MkDocs]({{ }}).

Furo: Sphinx Documentation Theme

by Tim Hopper

Documentation

Furo is a Sphinx theme written by Pradyun Gedam. It is a clean, customisable replacement for Sphinx’s default alabaster theme, with built-in light and dark modes, a responsive layout, and a focused sidebar.

Note

Furo’s latest release is 2025.12.19 (Furo uses calendar versioning), licensed MIT. Install via uv add --group docs furo or pip install furo.

When to use Furo

Furo is a strong default for any new Sphinx project that wants light and dark mode without spending time on theme configuration. It is biased toward smaller documentation sets where presenting the entire navigation hierarchy in the sidebar stays readable. For projects with deep, multi-level navigation (more than three or four levels), the Read the Docs theme (sphinx_rtd_theme) handles nested sidebars more comfortably.

Key Features

Automatic light and dark mode that follows the reader’s system preference
Built-in search via Sphinx’s standard search backend
Responsive layout that works on phone, tablet, and desktop
Minimal configuration: setting html_theme = "furo" is usually enough
Customisation hooks for colors, fonts, sidebar links, and an optional announcement banner
Accessible focus styles and keyboard navigation

Configuration

Furo is configured through Sphinx’s standard html_theme_options dictionary in conf.py:

docs/source/conf.py

html_theme = "furo"

html_theme_options = {
    "light_logo": "logo-light.png",
    "dark_logo": "logo-dark.png",
    "sidebar_hide_name": False,
    "navigation_with_keys": True,
    "announcement": "📢 New release: 2.0.0 is out!",
}

The full set of options is documented in the Furo customisation guide.

Projects Using Furo

pip, Python’s reference package installer
attrs, the class-building library
Black, the Python formatter
Urllib3, the HTTP client
Sigstore-python, the supply-chain signing client

Pros

Sensible defaults; no configuration needed for a usable result
Light and dark mode built in (rare among Sphinx themes)
Single-maintainer project with steady release cadence
Used by pip itself

Cons

Not optimized for sites with many levels of nested navigation
Single-maintainer projects carry the usual bus-factor risk
Customisation surface is intentionally narrower than the Read the Docs theme
Sphinx-specific; cannot be used with MkDocs or other generators

Learn More

Last updated on April 29, 2026

Flit hatch

Please submit corrections and feedback...