Sphinx Serializing HTML Extension

2.0.0 verified Tue May 12 auth: no python install: verified

sphinxcontrib-serializinghtml is a Sphinx extension that outputs "serialized" HTML files, specifically in JSON and Pickle formats. This enables external applications or custom post-processing tools to consume documentation content without needing to parse raw HTML. The library is currently at version 2.0.0 and follows a release cadence tied to Sphinx releases, with recent updates addressing dependency management and Python/Sphinx version compatibility.

pip install sphinxcontrib-serializinghtml

Common errors

error ModuleNotFoundError: No module named 'sphinxcontrib.serializinghtml' ↓

cause The `sphinxcontrib-serializinghtml` package has not been installed in the Python environment where Sphinx is being run.

fix

Install the package using pip: pip install sphinxcontrib-serializinghtml

error Unknown builder: json ↓

cause The `sphinxcontrib.serializinghtml` extension has not been added to the `extensions` list in your Sphinx project's `conf.py` file, preventing the 'json' (or 'pickle') builder from being registered.

fix

Add 'sphinxcontrib.serializinghtml' to the extensions list in your conf.py file:

extensions = [
    'sphinx.ext.autodoc',
    # ... other extensions
    'sphinxcontrib.serializinghtml',
]

error Unknown extension: serializinghtml ↓

cause The extension name is misspelled or incorrectly provided in the `extensions` list within Sphinx's `conf.py` file.

fix

Correct the extension name in conf.py to the exact string 'sphinxcontrib.serializinghtml':

extensions = [
    # ...
    'sphinxcontrib.serializinghtml',
]

Warnings

breaking Python 3.5, 3.6, 3.7, and 3.8 support was dropped in version 1.1.6. Version 2.0.0 and later require Python >= 3.9. ↓

fix Upgrade your Python environment to 3.9 or newer.

breaking The minimum required Sphinx version was raised to 5.0 in `sphinxcontrib-serializinghtml` version 1.1.6. Using older Sphinx versions with recent `sphinxcontrib-serializinghtml` releases will likely result in errors. ↓

fix Ensure your Sphinx installation is version 5.0 or newer (e.g., `pip install -U Sphinx`).

gotcha Older versions (e.g., 1.1.1) of `sphinxcontrib-serializinghtml` experienced circular import issues if Sphinx was directly listed as a dependency, causing build failures. This was addressed in later 1.1.x versions, specifically version 1.1.10 removed Sphinx as a required direct dependency to prevent such conflicts. ↓

fix Upgrade to `sphinxcontrib-serializinghtml` version 1.1.10 or later to avoid this specific circular import problem.

gotcha This extension provides special builders (`json` and `pickle`). To generate serialized output, you must explicitly use these builders (e.g., `make json` or `sphinx-build -b json`), not the default `html` builder. The output will be in `.fjson` and `.fpickle` files, not standard `.html`. ↓

fix When building your Sphinx project, use `make json` or `make pickle` (or `sphinx-build -b json` / `sphinx-build -b pickle`) to generate the desired serialized output.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 18.7M

3.10 alpine (musl) - - - 18.7M

3.10 slim (glibc) wheel 1.5s - 19M

3.10 slim (glibc) - - - 19M

3.11 alpine (musl) wheel - - 20.5M

3.11 alpine (musl) - - - 20.5M

3.11 slim (glibc) wheel 1.6s - 21M

3.11 slim (glibc) - - - 21M

3.12 alpine (musl) wheel - - 12.4M

3.12 alpine (musl) - - - 12.4M

3.12 slim (glibc) wheel 1.4s - 13M

3.12 slim (glibc) - - - 13M

3.13 alpine (musl) wheel - - 12.1M

3.13 alpine (musl) - - - 12.0M

3.13 slim (glibc) wheel 1.5s - 13M

3.13 slim (glibc) - - - 13M

3.9 alpine (musl) wheel - - 18.2M

3.9 alpine (musl) - - - 18.2M

3.9 slim (glibc) wheel 1.7s - 19M

3.9 slim (glibc) - - - 19M

Imports

sphinxcontrib.serializinghtml
wrong
```
import sphinxcontrib.serializinghtml
```
correct
```
# in conf.py
extensions = [
    'sphinxcontrib.serializinghtml'
]
```
This library is a Sphinx extension and should be enabled by adding its name (as a string) to the 'extensions' list in your Sphinx project's conf.py. Direct Python import statements are generally not used for enabling Sphinx extensions in conf.py, and historically caused circular import issues in older versions.

Quickstart last tested: 2026-04-24

After installing the library, enable it by adding 'sphinxcontrib.serializinghtml' to the 'extensions' list in your Sphinx project's `conf.py`. Then, build your documentation using the 'json' or 'pickle' builder, which are provided by this extension.

# 1. Create a Sphinx project (if you don't have one):
# sphinx-quickstart

# 2. In your conf.py file, add the extension:
# extensions = [
#     'sphinxcontrib.serializinghtml'
# ]

# 3. Build the documentation to JSON or Pickle format:
# From your project root (where Makefile or make.bat is located):
# make json
# or
# make pickle

# Alternatively, using sphinx-build directly:
# sphinx-build -b json -d _build/doctrees . _build/json
# sphinx-build -b pickle -d _build/doctrees . _build/pickle