---
id: nbsphinx-link
version: "1.4.1"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# nbsphinx-link — A sphinx extension for including notebook files outside sphinx source root

License: permissive · Maintenance: active · Downloads: 128.9K/mo

## What it is and what it does

nbsphinx-link solves the problem of including Jupyter notebooks in Sphinx documentation when those notebooks live outside the Sphinx source directory. Normally Sphinx restricts included files to the source tree, but this extension bridges that gap by letting you create lightweight .nblink JSON files that point to notebooks elsewhere on disk—useful for centralizing examples or shared notebook collections that multiple documentation projects reference.

The extension works by reading .nblink files (simple JSON with a "path" key pointing to a notebook and an optional "extra-media" array for associated images) and rendering the referenced notebook into your documentation build. It integrates directly into Sphinx's build pipeline and depends on nbsphinx to handle the actual notebook rendering.

Use it for:

- Include notebooks from a shared examples directory across multiple Sphinx documentation projects
- Reference notebooks stored in a separate repository or folder structure without copying them
- Build documentation that mixes RST files with external Jupyter notebooks using a single Sphinx config
- Manage notebook-based tutorials centrally while keeping documentation source trees lean

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Sphinx extension that lets you include Jupyter notebooks from directories outside your Sphinx source root by referencing them via .nblink JSON files.

Yes, if you use Sphinx and need to include Jupyter notebooks from outside your documentation source tree. Low install friction, active maintenance, permissive license, and no known vulnerabilities. The extension solves a specific but real Sphinx limitation with minimal overhead.

## Install

pip install nbsphinx-link
uv add nbsphinx-link
poetry add nbsphinx-link

## Installing nbsphinx-link

Before you install: Low friction install with active maintenance. Last release 77 days ago, repository not archived, and requires only nbsphinx and sphinx as dependencies.

License in practice: BSD-3-Clause permissive license allows use in most projects with minimal restrictions.

Quickstart:

pip install nbsphinx-link

# In conf.py:
extensions = ['nbsphinx_link']

# Create example.nblink:
{"path": "../examples/notebook.ipynb"}

# Reference in RST:
.. include:: example.nblink

Requires Python 3.10 or later; nbsphinx and sphinx must be installed and configured.

Verify before relying:

- Whether .nblink files support nested directory structures or only flat paths
- How media file paths are resolved when notebooks reference external assets
- Whether the extension handles notebook cell execution or only renders static output

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 128.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sphinx notebook inclusion, jupyter notebooks in sphinx docs, external notebook linking, sphinx extension notebooks, nblink files sphinx, include notebooks outside source, sphinx documentation notebooks, sphinx-extension, jupyter-notebooks, documentation-build

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