jupyter-sphinx

What it is and what it does

Jupyter Sphinx Extensions is a Sphinx plugin that executes Python code blocks embedded in your documentation at build time and captures their output—text, plots, tables, and interactive Jupyter widgets—inserting it into the final HTML or other output formats. It bridges the gap between static documentation and live, runnable examples by letting you write code directly in your .rst files and have it execute during the doc build, keeping examples in sync with your actual code.

The package depends on the full Jupyter ecosystem (ipykernel, ipython, ipywidgets, nbconvert, nbformat) plus Sphinx itself, so it's designed for projects that already use Jupyter and want to embed executable examples in their Sphinx docs. It's maintained by the Jupyter project and remains actively developed.

Use it for:

• Embed live Python examples in API documentation that execute and display output at doc build time.
• Create tutorial documentation with executable code blocks and rendered plots or tables.
• Include interactive Jupyter widgets in your Sphinx docs for exploratory examples.
• Ensure code examples in documentation stay synchronized with actual behavior by running them during builds.
• Build scientific or data-science project docs with embedded computational results and visualizations.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Jupyter Sphinx Extensions runs code embedded in Sphinx documentation and embeds its output—including images and interactive widgets—directly into the generated documentation.

Yes, if you maintain Sphinx documentation for a Jupyter-based project and want executable examples in your docs. The package is actively maintained, has low install friction, and solves a real problem—keeping code examples current and showing actual output. The unclear license treatment is a minor flag; verify it with the project if compliance is critical, but the raw text appears to be standard BSD.

Install

jupyter-sphinx on PyPI

pip install jupyter-sphinx

uv add jupyter-sphinx

poetry add jupyter-sphinx

Installing jupyter-sphinx

Before you install

Low friction installation with a pure-Python wheel. Active maintenance as of 2026-08-03 with 194 repository stars. Depends on six common Jupyter ecosystem packages (ipykernel, ipython, ipywidgets, nbconvert, nbformat, sphinx), all widely used and well-maintained.

License in practice

License treatment is unclear in the metadata. The raw text is a revised BSD license (permissive), but the SPDX field is null. Verify the exact license classification with the project before relying on it for compliance-sensitive work.

Quickstart

pip install jupyter_sphinx

# In conf.py (Sphinx configuration):
extensions = ['jupyter_sphinx']

# In .rst file:
.. jupyter-execute::

    print('Hello from Jupyter Sphinx')

Requires Python >=3.8 and a working Sphinx documentation setup with Jupyter kernel available at build time.

Verify before relying

• Whether the 'unclear' license treatment reflects a genuine ambiguity or a metadata gap that the project has since clarified.
• Support status for Python versions beyond 3.8 (current support statement is 'supports_current', but exact upper bound is unknown).
• Specific syntax and directive names for embedding executable code blocks in documentation.

Package facts

Evidence: jupyter_sphinx-0.5.3-py3-none-any.whl

Tags

More Sphinx packages