Install & Compatibility
Where this runs
tested against v2.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.4s · import 0.000s · 93MB
94MB installed
● package 94MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinx_sitemap
✓ extensions = ['sphinx_sitemap']
Add 'sphinx_sitemap' to the `extensions` list in your `conf.py`.
To get started, install the library and then enable the extension by adding 'sphinx_sitemap' to the `extensions` list in your Sphinx `conf.py`. Crucially, set the `html_baseurl` configuration variable to the root URL where your documentation will be hosted for correct sitemap generation.
# In conf.py, typically located in your Sphinx project's root directory
import os
project = 'My Awesome Docs'
copyright = '2026, Your Name'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx_sitemap', # Add this line to enable the extension
]
# *** ESSENTIAL for sitemap generation ***
# Set the base URL of your published documentation. This is critical for sitemap validity.
html_baseurl = os.environ.get('DOCS_BASE_URL', 'https://example.com/docs/')
# Optional: Enable 'lastmod' timestamps (requires Git repository with history)
# sitemap_show_lastmod = True
# Optional: Exclude specific pages or patterns from the sitemap
# sitemap_exclude_pages = ['excluded_page.html', '**/private/*']
# To generate the sitemap, navigate to your docs directory and run:
# sphinx-build -b html . _build
# The sitemap.xml will be generated in the _build directory.
Debug
Known issues
breakingOlder versions of `sphinx-sitemap` (prior to 2.9.0, specifically versions before 2.8.0) experienced compatibility issues with Sphinx 7.2.x due to internal API changes within Sphinx (e.g., TocTree refactoring, `pathlib.Path` objects, and changes to JS/CSS handling). Ensure you are using `sphinx-sitemap` 2.9.0 or newer if targeting Sphinx 7.2.x or later.fixUpgrade `sphinx-sitemap` to version 2.9.0 or newer: `pip install --upgrade sphinx-sitemap`. If an upgrade is not possible, pin Sphinx to a version `< 7.2.0`.
affects: < 2.9.0 with Sphinx >= 7.2.0
gotchaThe `html_baseurl` configuration variable in `conf.py` is absolutely critical for `sphinx-sitemap` to generate valid, absolute URLs in your `sitemap.xml`. If this variable is not set or contains an incorrect URL, the generated sitemap will be ineffective for search engines.fixAlways set `html_baseurl = 'https://your-docs-domain.com/path/'` in your `conf.py`. Ensure it accurately reflects the live URL of your documentation.
affects: All versions
gotchaFor multi-version or multi-language Sphinx projects, `sphinx-sitemap` generates a separate sitemap for each version/language. You must then manually create a `sitemapindex.xml` file that links to these individual sitemaps to properly inform search engines of all available content.fixRefer to the `sphinx-sitemap` documentation on 'Versioning Configuration' and 'Multilingual Configuration' for detailed instructions on creating a `sitemapindex.xml`.
affects: All versions
gotchaWhen `sitemap_show_lastmod = True` is enabled, the extension attempts to add `<lastmod>` timestamps based on Git's last update time for each page. This feature requires a full Git repository history to be available. Shallow clones, which are the default behavior in many Continuous Integration (CI) environments (e.g., GitHub Actions), are not supported and will result in the omission of `<lastmod>` tags.fixIn CI/CD pipelines, configure Git to perform a full clone (e.g., `fetch-depth: 0` for GitHub Actions) rather than a shallow clone if you intend to use `sitemap_show_lastmod`.
affects: All versions where `sitemap_show_lastmod` is used
gotchaAs of Sphinx version 5, the `language` configuration value defaults to 'en'. This can affect the default URL scheme generated by `sphinx-sitemap`. If the default `{lang}{version}{link}` scheme produces incorrect URLs, particularly in multi-language setups, you may need to explicitly customize `sitemap_url_scheme`.fixSet `sitemap_url_scheme` in your `conf.py` to match your desired URL structure (e.g., `sitemap_url_scheme = "{link}"` for no language/version prefix). affects: Sphinx >= 5 with `sphinx-sitemap`
Upgrade
Version history
2.9.0latest on PyPI · released Oct 6, 2025
Audit
Dependencies
SphinxrequiredCore dependency as it's a Sphinx extension.