Install & Compatibility
Where this runs
tested against v0.13.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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 94.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 7.1s · import 0.000s · 95MB
131MB installed
● package 131MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinxext.opengraph
✓ # In conf.py
extensions = [
'sphinxext.opengraph',
# ... other extensions
]
Sphinx extensions are activated by adding their module name to the 'extensions' list in conf.py, not via Python 'import' statements in user code.
To enable the extension, add 'sphinxext.opengraph' to the `extensions` list in your Sphinx project's `conf.py` file. The `ogp_site_url` configuration option is mandatory and must be set to the public URL of your documentation for Open Graph tags to function correctly. Optional settings like `ogp_image` and `ogp_social_cards` can further customize the generated metadata and social media previews.
# conf.py
extensions = [
'sphinxext.opengraph',
]
# REQUIRED: Set the public URL where your documentation is hosted
ogp_site_url = "https://docs.example.com/"
# Optional: Set a default image for pages without one
ogp_image = "https://docs.example.com/_static/logo.png"
# Optional: Enable social card generation (requires matplotlib extra)
ogp_social_cards = {
"enable": True,
"image": "_static/social_card_logo.png", # Path relative to HTML output root
}
Debug
Known issues
breakingSupport for Sphinx 4 was dropped in version 0.10.0. Projects using older Sphinx versions should upgrade `sphinxext-opengraph` cautiously or stick to an older version.fixUpgrade your Sphinx version to 5 or higher. If you need to stay on Sphinx 4, use `sphinxext-opengraph<0.10.0`.
affects: >=0.10.0
breakingPython 3.7 support was dropped in version 0.9.0. Users on Python 3.7 must upgrade their Python environment or remain on `sphinxext-opengraph<0.9.0`.fixUpgrade to Python 3.8 or newer. If you must use Python 3.7, use `sphinxext-opengraph<0.9.0`.
affects: >=0.9.0
gotchaThe `ogp_site_url` configuration option is critical. Without it, or if it's set incorrectly, the Open Graph metadata will not include absolute URLs and may not be properly recognized by social media platforms. Read the Docs users typically do not need to set this, as it is automatically detected.fixEnsure `ogp_site_url` is explicitly set in `conf.py` to the canonical public URL of your documentation, e.g., `ogp_site_url = "https://docs.example.com/"`.
affects: All versions
gotchaGenerating social media cards (`ogp_social_cards`) requires the optional `matplotlib` dependency. Furthermore, images used for social cards (e.g., `html_logo` or `ogp_social_cards['image']`) cannot be in SVG format due to Matplotlib limitations.fixInstall with `pip install sphinxext-opengraph[social_cards]`. Ensure any images intended for social cards are PNG or JPEG.
affects: All versions with social card feature (>=0.8.0)
gotchaWhen overriding Open Graph tags on a per-page basis using reStructuredText field lists (e.g., `:og:image:`), relative file paths for images, videos, and audio are not supported. Only absolute URLs can be used in these per-page overrides.fixUse absolute URLs for image, video, or audio paths when specifying them via per-page field lists.
affects: All versions
Upgrade
Version history
0.13.0latest on PyPI · released Aug 29, 2025
Audit
Dependencies
SphinxrequiredThis is a Sphinx extension and requires Sphinx to operate.
matplotliboptionalRequired for generating social media card PNGs. Can be installed with the `social_cards` extra.