---
id: nbsphinx
version: "0.9.8"
license: MIT
license_treatment: permissive
maintenance: active
---

# nbsphinx — Jupyter Notebook Tools for Sphinx

License: permissive · Maintenance: active · Downloads: 1.9M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

jupyter notebook sphinx documentation, sphinx ipynb parser, include jupyter notebooks in sphinx docs, notebook to sphinx html, sphinx jupyter integration, document jupyter code cells, sphinx notebook extension, jupyter-integration, documentation-generation

[View on SkillFed](https://skillfed.io/packages/nbsphinx) · [View on PyPI](https://pypi.org/project/nbsphinx/)