nbsphinx

What it is and what it does

nbsphinx bridges Jupyter Notebooks and Sphinx documentation by treating .ipynb files as native Sphinx source. When you add notebook filenames to your Sphinx toctree, the extension parses them, renders code cells and outputs as documentation, and automatically executes any notebooks that lack stored output. This lets you write executable examples or tutorials as Jupyter Notebooks and have them appear seamlessly in your Sphinx-built HTML or LaTeX docs.

The package depends on nbconvert and nbformat to handle notebook I/O, sphinx for the documentation framework, and supporting libraries (docutils, jinja2, traitlets) for rendering and configuration. It's designed for technical documentation, education, and research contexts where executable code examples are valuable.

Use it for:

• Include executable Jupyter tutorials or walkthroughs directly in Sphinx documentation without manual conversion.
• Build API documentation that interleaves narrative text with runnable code examples from notebooks.
• Create scientific or research documentation where computed results are embedded in the final HTML or PDF output.
• Maintain a single notebook source that serves both as a standalone Jupyter file and as part of your Sphinx docs.
• Automatically regenerate documentation output from notebooks during the build, keeping examples in sync with code.

Worth the install?

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

nbsphinx is a Sphinx extension that parses Jupyter Notebook files (.ipynb) as documentation source, rendering notebook code cells and their outputs in Sphinx-generated HTML and LaTeX documentation, with automatic execution of unevaluated notebooks during the build.

Yes. nbsphinx is actively maintained, has low install friction, carries no security vulnerabilities, and solves a specific and well-defined problem: integrating Jupyter Notebooks into Sphinx documentation. Install it if you want to include executable notebooks or notebook-style examples in your Sphinx docs; skip it if your documentation doesn't use notebooks.

Install

nbsphinx on PyPI

pip install nbsphinx

uv add nbsphinx

poetry add nbsphinx

Installing nbsphinx

Before you install

Low friction: pure Python wheel with six runtime dependencies. Actively maintained with a recent release (259 days ago) and steady commit activity.

License in practice

MIT license (permissive) places no restrictions on use, modification, or distribution in your own projects.

Quickstart

pip install nbsphinx

Edit conf.py and add 'nbsphinx' to extensions:
  extensions = ['nbsphinx']

Add notebook filenames to index.rst toctree:
  .. toctree::
     my_notebook.ipynb

Requires Python >= 3.8 and an existing Sphinx documentation project.

Verify before relying

• Whether automatic notebook execution during build requires specific Jupyter kernel or environment setup beyond the listed dependencies.
• Performance characteristics when building documentation with many or large notebooks.

Package facts

Evidence: nbsphinx-0.9.8-py3-none-any.whl

Keywords: Sphinx, Jupyter, notebook

Tags

More Sphinx packages