Jupyter Notebook Tools for Sphinx

0.9.8 · active · verified Sat Apr 11

nbsphinx is a Sphinx extension that provides a source parser for *.ipynb files. It allows Sphinx to directly include Jupyter Notebooks, showing code cells and their results in both HTML and LaTeX output. Un-evaluated notebooks are automatically executed during the Sphinx build process. The library is actively maintained, with version 0.9.8 being the current release, and follows a regular release cadence.

Warnings

breaking Version 0.9.0 introduced significant internal changes, splitting `nbsphinx.py` into a package structure and modifying how custom HTML/CSS for thumbnail galleries work. Custom CSS for galleries or direct usage of `sphinx_gallery.load_style` may break.
Fix: Review your `conf.py` and custom CSS files for gallery configurations and adjust according to the new structure, especially regarding `nbsphinx-gallery.css`.
gotcha Notebooks included in a Sphinx `toctree` must have a title (e.g., a top-level Markdown heading in the first cell). Failing to do so can lead to 'missing title' errors during the build process.
Fix: Ensure the first cell of every `.ipynb` file intended for the `toctree` contains a title (e.g., `# My Notebook Title`).
gotcha Compatibility with Sphinx versions can be sensitive. For instance, nbsphinx 0.9.7 temporarily disabled support for Sphinx 8.2+, which was re-enabled in 0.9.8. Always check release notes for specific Sphinx version compatibility.
Fix: Refer to the nbsphinx documentation or release notes for the exact Sphinx version compatibility. If encountering issues, try aligning `nbsphinx` and Sphinx versions.
gotcha It is highly recommended to clear all output cells from notebooks before committing them to version control (e.g., Git). Notebooks with embedded outputs can lead to large repository sizes and difficult-to-manage diffs. `nbsphinx` will execute notebooks without outputs during the build.
Fix: Clear notebook outputs using 'Cell' -> 'All Output' -> 'Clear' in Jupyter, or use tools like `nbstripout` before committing to Git.
gotcha nbsphinx 0.9.1 included a change to disable `pandoc`'s 'smart' option specifically for `pandoc` versions 2.0 and above. If using `pandoc`, be aware of how this might affect Markdown rendering.
Fix: No direct fix needed unless specific `pandoc` 'smart' conversions are desired; then refer to `nbsphinx` configuration options related to `pandoc`.

Install

pip install nbsphinx Install from PyPI

Imports

nbsphinx
```
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'nbsphinx',
    # ... other extensions
]
```
nbsphinx is enabled by adding its name as a string to the 'extensions' list in your Sphinx 'conf.py' file.

Quickstart

To integrate Jupyter notebooks into Sphinx documentation, first install `nbsphinx` and `ipykernel`. Then, modify your `conf.py` to include `'nbsphinx'` in the `extensions` list. Finally, reference your `.ipynb` files (without the extension) within a `.. toctree::` directive in your `.rst` files. Notebooks should have a title (e.g., a Markdown heading in the first cell) to be correctly included.

# my_notebook.ipynb (Jupyter Notebook file)
# (Ensure this notebook has a title as its first cell, e.g., '# My Notebook Title')

import pandas as pd
df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
print(df)

# conf.py (Sphinx configuration file)
import os

project = 'My Project'
copyright = '2026, Your Name'
extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax', # Often useful with notebooks
    'ipykernel' # Needed if notebooks are to be executed
]
html_theme = 'alabaster'

# index.rst (Sphinx master document)
..
  My Project
  ==========

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   my_notebook

# To build the documentation:
# 1. Create a Sphinx project: sphinx-quickstart (answer prompts)
# 2. Update conf.py and index.rst as shown above
# 3. Create my_notebook.ipynb
# 4. Run: sphinx-build -b html . _build

view raw JSON →