{"id":2515,"library":"furo","title":"Furo Sphinx Theme","description":"Furo is a clean, customisable, and modern Sphinx documentation theme. It is actively developed with frequent releases, often monthly or bi-monthly, to keep pace with Sphinx updates and introduce minor enhancements and fixes. The current version is 2025.12.19.","status":"active","version":"2025.12.19","language":"en","source_language":"en","source_url":"https://github.com/pradyunsg/furo","tags":["sphinx","documentation","theme","rst","markdown","docs"],"install":[{"cmd":"pip install furo","lang":"bash","label":"Install Furo"}],"dependencies":[{"reason":"Furo is a theme for Sphinx and requires Sphinx to build documentation.","package":"Sphinx","optional":false}],"imports":[{"note":"Furo is a Sphinx theme, not a standard Python library meant for direct import in user Python code. It is activated via the `conf.py` configuration file.","symbol":"Theme activation","correct":"html_theme = 'furo' # in conf.py"}],"quickstart":{"code":"# 1. Install Furo and Sphinx\n# pip install furo sphinx\n\n# 2. Create a Sphinx project (if you haven't already)\n# sphinx-quickstart # Follow prompts, e.g., 'y' for separate build/source dirs\n\n# 3. Edit your conf.py file\n# Open docs/conf.py (or your source directory's conf.py)\n# Find or add the following line:\n\n# conf.py example snippet:\n\n# -- Project information -----------------------------------------------------\nproject = 'My Awesome Project'\ncopyright = '2023, Your Name'\nauthor = 'Your Name'\nrelease = '0.1.0'\n\n# -- General configuration ---------------------------------------------------\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinx.ext.viewcode',\n]\n\n# -- Options for HTML output -------------------------------------------------\nhtml_theme = 'furo'\n\nhtml_theme_options = {\n    \"navigation_with_keys\": True,\n    \"sidebar_hide_name\": True,\n}\n\n# 4. Build your documentation (from the docs directory)\n# make html\n# Open _build/html/index.html in your browser","lang":"python","description":"This quickstart guides you through setting up a basic Sphinx project and enabling the Furo theme. Ensure Sphinx is installed, then create or update your `conf.py` to specify `html_theme = 'furo'` and optionally configure theme options."},"warnings":[{"fix":"Ensure your Sphinx installation meets Furo's current requirements. Update Sphinx: `pip install -U sphinx`.","message":"Furo frequently updates its minimum supported Sphinx version. Using an older Sphinx installation may lead to build failures or rendering issues.","severity":"breaking","affected_versions":"Furo 2024.01.29 removed support for Sphinx < 6.0. Later versions (e.g., 2025.12.19) may further bump required ranges. Always check the latest Furo release notes."},{"fix":"Refer to the official Furo documentation's 'Customisation' section for a complete list of available `html_theme_options` and their expected values. Validate your `conf.py` settings carefully.","message":"Customizing Furo is done via the `html_theme_options` dictionary in `conf.py`. Incorrect option names, unexpected value types, or invalid paths can lead to silent failures or unexpected theme behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For minor tweaks, utilize `html_theme_options`. For significant visual overhauls, be prepared to explore Sphinx's `html_css_files` and `html_js_files` options, potentially alongside custom SASS compilation, as detailed in advanced Sphinx theme documentation.","message":"Furo is designed for a clean, minimalist aesthetic. While highly customizable through theme options, achieving extensive visual changes that deviate significantly from its base design might require deep overrides of CSS/JavaScript, which can be more complex than expected for users new to Sphinx's asset pipeline.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}