nbval
A py.test plugin to validate Jupyter notebooks
Decision gist · record as of 2026-08-14
Yes, if you maintain Jupyter notebooks as part of your documentation or reference material and want to ensure they stay executable and correct. The low install friction and permissive license make it a practical choice. However, note that the project is aging (last release March 2024)—verify compatibility with your current pytest and Jupyter versions before relying on it in new projects.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires pytest, jupyter-client, and ipykernel to be installed; notebooks must be in .ipynb format.
- Low install friction with a pure-Python wheel.
- Maintenance is aging—last release was in March 2024—but the repository remains active and unarchived with modest community engagement (453 stars).
License · maintenance · safety
permissive license (permissive) — BSD license (permissive) means you can use, modify, and distribute nbval freely in commercial and private projects with minimal restrictions.
last release 2024-03-04 (893 days) · last repo commit 2025-09-17 · 453 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 603,339 downloads/mo, #5,811 on PyPI
Alternatives
Verify before relying
pip install nbval
pytest --nbval my_notebook.ipynb- Whether the aging maintenance status (893 days since last release) affects compatibility with recent Jupyter/pytest versions.
- Performance characteristics when running large notebooks or many notebooks in parallel.
What it is and what it does
nbval is a pytest plugin that integrates Jupyter notebooks into your test suite. Instead of manually running notebooks to check outputs, nbval treats each code cell as a test case, executing it and comparing the actual output against what was stored in the .ipynb file. This ensures that reference notebooks, documentation, and examples stay in sync with their expected behavior and don't break silently over time.
The plugin works by launching an IPython kernel, sending each cell's code to it via jupyter-client, and collecting the output messages. It supports output sanitization via regex rules, integration with pytest-cov for coverage reporting, and parallel execution via pytest-xdist (with the `--dist loadscope` flag). You can run all notebooks in a directory with `pytest --nbval`, or target specific files, and use `--nbval-lax` to only check cells marked with `#NBVAL_CHECK_OUTPUT`.
Use it for
- Validate that tutorial and documentation notebooks execute without errors and produce expected outputs.
- Catch breaking changes in dependencies by running notebooks as part of your CI/CD pipeline.
- Ensure reproducibility of computational results stored in reference notebooks.
- Generate code coverage reports from notebook execution using pytest-cov integration.
- Run notebooks in parallel across multiple workers while keeping each notebook's cells on the same kernel.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you maintain Jupyter notebooks as part of your documentation or reference material and want to ensure they stay executable and correct.
The low install friction and permissive license make it a practical choice. However, note that the project is aging (last release March 2024)—verify compatibility with your current pytest and Jupyter versions before relying on it in new projects.
Install
nbval on PyPI
Before you install
Low install friction with a pure-Python wheel. Maintenance is aging—last release was in March 2024—but the repository remains active and unarchived with modest community engagement (453 stars).
Requires pytest, jupyter-client, and ipykernel to be installed; notebooks must be in .ipynb format.
License in practice
BSD license (permissive) means you can use, modify, and distribute nbval freely in commercial and private projects with minimal restrictions.
Quickstart
pip install nbval
pytest --nbval my_notebook.ipynbVerify before relying
- Whether the aging maintenance status (893 days since last release) affects compatibility with recent Jupyter/pytest versions.
- Performance characteristics when running large notebooks or many notebooks in parallel.
Package facts
| License | permissive license permissive |
| Python support | Supports the current Python release >=3.7, <4 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 5 packagespytestjupyter-clientnbformatipykernelcoverage |
| Maintenance | Aging 893 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 603,339 / month, #5,811 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Framework :: IPythonFramework :: PytestLicense :: OSI Approved :: BSD LicenseProgramming Language :: Python :: 3Topic :: Software Development :: Testing |
Evidence: nbval-0.11.0-py2.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 › “ipynb test execution”
- nbvalA pytest plugin that treats Jupyter notebooks as test files,…
- testbooktestbook lets you write unit tests for Jupyter Notebooks in separate…
- mkdocs-jupyterConverts Jupyter notebooks and Python scripts into pages for mkdocs…
Give your agent the search over MCP, or paste the wish link into any chat.
More Testing packages
Pluggy provides a plugin system that lets you define hook specifications and register implementations to be called in sequence, enabling extensible Python applications without tight coupling.
Install it if you're building an extensible application or framework.
pytest is a testing framework that lets you write test functions using plain assert statements and automatically discovers and runs them, with detailed failure reporting.
virtualenv creates isolated Python environments where packages can be installed independently without affecting the system Python or other projects.
Coverage.py measures which lines of Python code are executed during test runs, reporting coverage percentages and identifying untested code paths.
Install it if you want to measure test completeness or enforce coverage thresholds in your project.
pytest-asyncio is a pytest plugin that enables writing and running async test functions using the asyncio library, allowing developers to await code directly within test cases.
Install it if you write tests for any asyncio-based code.
A pytest plugin that generates test reports in Common Test Report Format (CTRF) as JSON, compatible with pytest-xdist and pytest-playwright for distributed and browser-based testing.
Install it if you need CTRF-formatted test output for CI/CD integration or cross-tool reporting.
See also ipytest · nb-clean · nbdev · nbmake · nbqa · pybatfish · testbook · nbstripout · execnb · jupyter-nbmodel-client