Install & Compatibility
Where this runs
tested against v1.6.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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 101.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.9s · import 0.000s · 102MB
103MB installed
● package 103MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinxcontrib.redoc
✓ extensions = ['sphinxcontrib.redoc']
The extension is enabled by adding 'sphinxcontrib.redoc' to the 'extensions' list in Sphinx's conf.py.
To quickly integrate sphinxcontrib-redoc, first install the package. Then, enable the extension by adding 'sphinxcontrib.redoc' to the `extensions` list in your Sphinx `conf.py`. Define your OpenAPI specifications using the `redoc` configuration variable, which is a list of dictionaries. Each dictionary specifies the API's name, the output HTML page path, the path (local or URL) to the OpenAPI spec, and optional ReDoc rendering options. You must also create an RST file (e.g., `api/index.rst`) for each defined page to ensure it's included in Sphinx's table of contents and provides a target for the rendered documentation.
# conf.py
import os
project = 'My API Docs'
copyright = '2026, Your Name'
extensions = [
'sphinxcontrib.redoc',
'sphinx.ext.autodoc', # Example of another common extension
]
# Configure sphinxcontrib-redoc
redoc = [
{
'name': 'My Awesome API',
'page': 'api/index', # Output HTML page path relative to build directory
'spec': 'openapi.yaml', # Path to OpenAPI spec relative to conf.py
'embed': True, # Embed the spec into the HTML page
'opts': {
'lazy-rendering': True,
'native-scrollbars': True,
'hide-hostname': True,
'expand-responses': ['200', '201'],
}
},
]
# Example of a minimal index.rst or api/index.rst
# My Awesome API
# ==============
#
# .. toctree::
# :maxdepth: 2
#
# .. raw:: html
#
# <div id="redoc-container"></div>
# Make sure the openapi.yaml exists in your docs folder for a local spec.
# Or use a remote URL: 'spec': 'https://petstore.swagger.io/v2/swagger.json'
Debug
Known issues
breakingVersion 1.6.0 dropped official support for Python 3.4. Ensure you are using Python 3.5 or newer.fixUpgrade your Python environment to 3.5 or later.
affects: >=1.6.0
gotchaReDoc can experience performance issues when rendering very large or complex OpenAPI specifications, leading to slow page load times in the generated documentation.fixConsider using ReDoc options like `lazy-rendering` or `native-scrollbars` in your `redoc` configuration to mitigate performance impact for large specs.
affects: All
gotchaWhen `embed` is set to `True`, the extension currently does not support embedding OpenAPI specifications from external HTTP(s) links; only local file paths are supported for embedding.fixFor embedded specs, provide a local file path for the 'spec' option. For external specs, set `embed: False`.
affects: All
gotchaAs of Sphinx 8, subsequent builds may produce a `WARNING: Aborted attempted copy from ... redoc.js` message. While often harmless, it can clutter build logs.fixCurrently, there is no official fix from `sphinxcontrib-redoc`. You may need to ignore this warning or monitor upstream for updates.
affects: Sphinx >= 8, sphinxcontrib-redoc < 2.0 (if ever released)
gotchaThe `redoc.js` library bundled with `sphinxcontrib-redoc` (last updated with v1.21.2 in 1.4.0, with minor updates up to 1.6.0) is potentially outdated. Newer ReDoc versions offer better features and bug fixes.fixOverride the `redoc_uri` Sphinx option to point to a more current ReDoc CDN, e.g., `redoc_uri = 'https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js'`.
affects: All
gotchaThe HTML page generated by `sphinxcontrib-redoc` is not automatically included in Sphinx's `toctree` (table of contents).fixYou must explicitly create a stub `.rst` file (e.g., `api.rst` or `api/index.rst`) and include it in your main `toctree` directive within your Sphinx project. This file will then be overwritten or used as the target for the ReDoc output.
affects: All
Upgrade
Version history
1.6.0latest on PyPI · released Apr 17, 2020
Audit
Dependencies
No dependency data recorded yet.