{"id":8670,"library":"sphinx-favicon","title":"Sphinx Favicon","description":"Sphinx Favicon is an active Sphinx extension, currently at version 1.1.0, that enhances the ability to add custom favicons to Sphinx HTML documentation. It allows users to define favicons directly in `conf.py` with various attributes like `rel`, `sizes`, `href`, or `name`, providing more flexibility than Sphinx's default `favicon.ico` support. The library maintains a steady release cadence with recent updates focusing on bug fixes and dependency modernization.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/tcmetzger/sphinx-favicon","tags":["sphinx","documentation","favicon","extension","html"],"install":[{"cmd":"pip install sphinx-favicon","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required runtime environment.","package":"Python","optional":false},{"reason":"Core dependency as it is a Sphinx extension.","package":"Sphinx","optional":false}],"imports":[{"note":"Between v0.2 and v1.0, the module name of the extension changed from `sphinx-favicon` to `sphinx_favicon` to conform with Python standards. Ensure your `conf.py` is updated.","wrong":"extensions = ['sphinx-favicon']","symbol":"Extension Enablement","correct":"extensions = ['sphinx_favicon']"}],"quickstart":{"code":"# conf.py\n\n# Add the extension to the list of enabled Sphinx extensions\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx_favicon',\n]\n\n# Configure the directory for static files (where your favicon images will be)\nhtml_static_path = ['_static']\n\n# Define your favicons. Ensure 'icon.png' exists in your _static directory.\nfavicons = [\n    {\"href\": \"icon.png\"},\n    {\"rel\": \"apple-touch-icon\", \"href\": \"apple-touch-icon.png\"}\n]","lang":"python","description":"To quickly integrate `sphinx-favicon` into your Sphinx project, first ensure your favicon images (e.g., `icon.png`, `apple-touch-icon.png`) are placed in your `_static` directory. Then, modify your `conf.py` file to include `sphinx_favicon` in your `extensions` list and configure the `favicons` list with paths to your images. The `html_static_path` must be defined if using relative paths for favicons."},"warnings":[{"fix":"Update your `conf.py` file: change `extensions = ['sphinx-favicon']` to `extensions = ['sphinx_favicon']`.","message":"The extension module name changed from `sphinx-favicon` to `sphinx_favicon` in version 1.0. Older configurations using `sphinx-favicon` in the `extensions` list will break.","severity":"breaking","affected_versions":"< 1.0"},{"fix":"Ensure `html_static_path = ['_static']` (or your chosen static directory) is set in your `conf.py` file, and your favicon images are within that directory.","message":"When using relative paths for your favicon images (e.g., `\"href\": \"icon.png\"`), the `html_static_path` variable MUST be defined in `conf.py` and point to the directory containing your static files. If omitted, Sphinx may not locate your favicons.","severity":"gotcha","affected_versions":">= 1.0"},{"fix":"If using `sphinx-favicon`, rely on the `favicons` list for all your favicon definitions for best results. Avoid setting `html_favicon` in `conf.py` if `favicons` provides the desired functionality.","message":"Sphinx has a built-in `html_favicon` configuration option for a single ICO, PNG, SVG, or GIF favicon. While `sphinx-favicon` enhances this, using both `html_favicon` and `favicons` simultaneously can lead to unexpected behavior or redundant output. Prioritize `sphinx-favicon`'s `favicons` for comprehensive control.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change the entry in your `conf.py` from `extensions = ['sphinx-favicon']` to `extensions = ['sphinx_favicon']`.","cause":"Using the old extension module name 'sphinx-favicon' in `conf.py` after upgrading to version 1.0 or newer.","error":"Unknown extension: sphinx-favicon"},{"fix":"Verify that your favicon images exist in the specified `_static` directory (or wherever `html_static_path` points). Ensure `html_static_path` is correctly set in `conf.py`. Double-check the `href` values in your `favicons` list for typos.","cause":"The favicon image path is incorrect, or `html_static_path` is not configured correctly for relative paths, or the favicon definition itself is malformed.","error":"Favicon not appearing in browser tabs or bookmarks."}]}