nbsphinx-link
A sphinx extension for including notebook files outside sphinx source root
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.10 or later; nbsphinx and sphinx must be installed and configured.
- Low friction install with active maintenance.
- Last release 77 days ago, repository not archived, and requires only nbsphinx and sphinx as dependencies.
License · maintenance · safety
BSD-3-Clause (permissive) — BSD-3-Clause permissive license allows use in most projects with minimal restrictions.
last release 2026-05-29 (77 days) · last repo commit 2026-05-29 · 39 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 128,941 downloads/mo, #11,690 on PyPI
Alternatives
Verify before relying
pip install nbsphinx-link
# In conf.py:
extensions = ['nbsphinx_link']
# Create example.nblink:
{"path": "../examples/notebook.ipynb"}
# Reference in RST:
.. include:: example.nblink- 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
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 on this page. Verify before relying on it.
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
nbsphinx-link on PyPI
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.
Requires Python 3.10 or later; nbsphinx and sphinx must be installed and configured.
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.nblinkVerify 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 the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 2 packagesnbsphinxsphinx |
| Maintenance | Actively maintained 77 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 128,941 / month, #11,690 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Intended Audience :: DevelopersProgramming Language :: PythonProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12 |
Evidence: nbsphinx_link-1.4.1-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “sphinx notebook inclusion”
- nbsphinx-linkA Sphinx extension that lets you include Jupyter notebooks from…
- sphinxcontrib-youtubeAdds Sphinx directives to embed YouTube, Vimeo, and Peertube videos…
- nbsphinxnbsphinx is a Sphinx extension that parses Jupyter Notebook files…
Give your agent the search over MCP, or paste the wish link into any chat.
More Sphinx packages
Parses Python docstrings in ReST, Google, Numpydoc, and Epydoc formats, extracting structured information like descriptions, parameters, return types, and exceptions.
Install it if you need to programmatically read and extract structured data from Python docstrings.
Sphinx generates professional documentation from reStructuredText source files, producing HTML, PDF, EPUB, and other formats with automatic cross-references, code highlighting, and hierarchical navigation.
A Sphinx extension that outputs documentation in serialized HTML formats (JSON and pickle) alongside standard HTML.
Alabaster is a clean, responsive Sphinx theme for documentation that requires Python 3.10 or newer and Sphinx 6.2 or newer.
A Sphinx extension that generates HTML help files from reStructuredText documentation source.
A Sphinx extension that converts documentation source files into QtHelp format, enabling integration with Qt-based help systems and documentation viewers.
However, be aware that maintenance is dormant—if you rely on it long-term, monitor Sphinx compatibility and consider whether QtHelp remains the right format for your…
See also nbsphinx · pyprojroot · myst-nb · sphinxcontrib-youtube · sphinx_mdinclude · importnb · sphinx-substitution-extensions · jupyter-sphinx · ipynb · mkdocs-jupyter