sphinx-favicon

What it is and what it does

Sphinx Favicon is a Sphinx extension that simplifies adding multiple favicon formats to HTML documentation. Instead of relying on Sphinx's built-in single-favicon support, it lets you define a list of favicon configurations directly in conf.py, each with a custom href and rel attribute (icon, apple-touch-icon, etc.). The extension generates the appropriate link tags in the HTML head during the build.

It handles both local files (resolved relative to html_static_path) and remote URLs. The extension depends on sphinx for the build framework, imagesize for reading image dimensions, and requests for fetching remote resources. It requires Python 3.10 or later and is classified as Production/Stable, though development has slowed (last release 183 days ago).

Use it for:

• Add multiple favicon sizes for different browsers and devices in a single configuration block
• Serve favicons from a remote URL while keeping documentation source in version control
• Configure apple-touch-icon links for iOS home-screen shortcuts without manual HTML editing
• Migrate from Sphinx's single favicon.ico to a multi-format favicon strategy

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Sphinx extension that injects custom favicon link tags into HTML documentation, supporting multiple formats and rel attributes configured directly in conf.py.

Yes, if you maintain Sphinx documentation and need multi-format favicon support beyond Sphinx's built-in single-favicon option. The extension is stable, permissively licensed, and has low install friction. However, maintenance is aging (last release 183 days ago), so verify compatibility with your current Sphinx version before relying on it for production builds.

Install

sphinx-favicon on PyPI

pip install sphinx-favicon

uv add sphinx-favicon

poetry add sphinx-favicon

Installing sphinx-favicon

Before you install

Low friction: pure Python wheel with three lightweight runtime dependencies. Maintenance status is aging—last release 183 days ago, repository not archived but with modest activity (24 stars).

License in practice

MIT license (permissive): you can use, modify, and redistribute this extension freely in commercial or private projects with minimal restrictions.

Quickstart

pip install sphinx-favicon

# In conf.py:
extensions = ["sphinx_favicon"]
html_static_path = ["_static"]
favicons = [
    {"href": "icon.svg"},
    {"rel": "apple-touch-icon", "href": "https://example.com/apple-touch-icon.png"}
]

Requires Python 3.10 or later; html_static_path must be set if using relative favicon paths

Verify before relying

• Whether imagesize and requests are actually invoked at build time or only conditionally
• Performance impact when processing many favicons or remote URLs during builds
• Compatibility with Sphinx versions beyond those tested in the fact sheet

Package facts

Evidence: sphinx_favicon-1.1.0-py3-none-any.whl

Keywords: sphinx, extension, favicon, meta html

Tags

More Utilities packages