---
id: sphinx-favicon
version: "1.1.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# sphinx-favicon — Sphinx Extension adding support for custom favicons

License: permissive · Maintenance: aging · Downloads: 201.4K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 201.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx favicon extension, add custom favicons sphinx, favicon html meta tags, sphinx documentation favicon, apple touch icon sphinx, favicon rel attributes, sphinx html head customization, sphinx-extension, documentation-tooling

[View on SkillFed](https://skillfed.io/packages/sphinx-favicon) · [View on PyPI](https://pypi.org/project/sphinx-favicon/)