Install & Compatibility
Where this runs
tested against v0.9.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 116.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.8s · import 0.000s · 112MB
118MB installed
● package 118MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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
Debug
Known issues
breakingVersion 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.fixReview your `conf.py` and custom CSS files for gallery configurations and adjust according to the new structure, especially regarding `nbsphinx-gallery.css`.
affects: 0.9.0 and later
gotchaNotebooks 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.fixEnsure the first cell of every `.ipynb` file intended for the `toctree` contains a title (e.g., `# My Notebook Title`).
affects: All versions
gotchaCompatibility 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.fixRefer to the nbsphinx documentation or release notes for the exact Sphinx version compatibility. If encountering issues, try aligning `nbsphinx` and Sphinx versions.
affects: 0.9.7 (with Sphinx 8.2+), potentially other versions with new Sphinx releases.
gotchaIt 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.fixClear notebook outputs using 'Cell' -> 'All Output' -> 'Clear' in Jupyter, or use tools like `nbstripout` before committing to Git.
affects: All versions
gotchanbsphinx 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.fixNo direct fix needed unless specific `pandoc` 'smart' conversions are desired; then refer to `nbsphinx` configuration options related to `pandoc`.
affects: 0.9.1 and later (with pandoc >= 2.0)
Upgrade
Version history
0.9.8latest on PyPI · released Nov 28, 2025
Audit
Dependencies
Sphinxrequirednbsphinx is a Sphinx extension and requires Sphinx to function.
docutilsrequiredRequired for parsing; version >= 0.18.1 is needed since nbsphinx 0.9.4.
ipykerneloptionalRequired for executing notebooks during the Sphinx build process.
pandocoptionalRecommended for certain advanced notebook conversions or features, though not always strictly required for basic functionality.