# Furo: Sphinx Documentation Theme


Furo is a [Sphinx](https://pydevtools.com/handbook/reference/sphinx.md) theme written by [Pradyun Gedam](https://pradyunsg.me/). 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`:

```python {filename="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](https://pradyunsg.me/furo/customisation/).

## Projects Using Furo

* [pip](https://pip.pypa.io/), Python's reference package installer
* [attrs](https://www.attrs.org/), the class-building library
* [Black](https://black.readthedocs.io/), the Python formatter
* [Urllib3](https://urllib3.readthedocs.io/), the HTTP client
* [Sigstore-python](https://sigstore.github.io/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

* [Furo Documentation](https://pradyunsg.me/furo/)
* [Furo GitHub Repository](https://github.com/pradyunsg/furo)
* [Customisation Guide](https://pradyunsg.me/furo/customisation/)
* [Sphinx Reference](https://pydevtools.com/handbook/reference/sphinx.md)