---
id: testbook
version: "0.4.2"
license: BSD
license_treatment: permissive
maintenance: dormant
---

# testbook — A unit testing framework for Jupyter Notebooks

License: permissive · Maintenance: dormant · Downloads: 105.1K/mo

## What it is and what it does

testbook is a unit testing framework that lets you write conventional Python unit tests for Jupyter Notebooks without embedding tests inside the notebooks themselves. Instead of mixing test code with notebook cells, you write separate test files that load and execute a notebook, then extract and assert on its outputs and variables. It depends on nbformat to parse notebooks and nbclient to execute them, bridging the gap between notebook-based development and traditional test-driven development practices.

The package treats .ipynb files as importable modules within your test suite. You decorate a test function with @testbook, pointing it to a notebook path, and the decorator handles notebook execution and provides a testbook object (tb) that lets you retrieve variables and functions defined in the notebook. This approach is useful for data science and analytics workflows where notebooks are primary development artifacts but you still want automated test coverage.

Use it for:

- Test data processing pipelines defined in Jupyter notebooks without rewriting them as Python modules
- Validate notebook outputs and intermediate variables in a CI/CD pipeline
- Ensure notebook functions produce expected results when dependencies or data change
- Build regression tests for analytical or scientific notebooks shared across a team
- Verify notebook cells execute without errors before publishing or sharing them

## Worth the install?

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

testbook lets you write unit tests for Jupyter Notebooks in separate Python test files, treating .ipynb files like .py modules and executing notebook code within test functions.

Yes, with caution. testbook fills a real gap for testing notebook-based code, and the low install friction and permissive license make it accessible. However, the package is dormant—no releases since 2021-06-02—which raises questions about compatibility with modern Python and Jupyter versions. If your notebooks target Python 3.6–3.8 and stable Jupyter dependencies, it should work; for newer environments, verify compatibility before committing to production use.

## Install

pip install testbook
uv add testbook
poetry add testbook

## Installing testbook

Before you install: Low friction install with just two runtime dependencies (nbformat, nbclient). However, the package is dormant—last release was 2021-06-02, though the repository remains active with a recent commit on 2024-08-25. No active maintenance signal.

License in practice: BSD license is permissive, allowing commercial and private use with minimal restrictions. No licensing friction for most use cases.

Quickstart:

pip install testbook

from testbook import testbook

@testbook('/path/to/notebook.ipynb', execute=True)
def test_func(tb):
    func = tb.get("func")
    assert func(1, 2) == 3

Requires a Jupyter kernel installed separately (e.g., ipykernel via pip install ipykernel) to execute notebooks during tests.

Verify before relying:

- Whether testbook works with modern Python versions beyond 3.8, given classifiers list only through 3.8
- Current compatibility with recent nbformat and nbclient versions, given no releases since 2021-06-02
- Whether dormant status affects bug fixes or compatibility with newer Jupyter ecosystem changes

## Package facts

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

## Tags

jupyter notebook unit testing, test ipynb files, notebook test framework, jupyter testing library, notebook code testing, ipynb test runner, jupyter notebook testing, jupyter-testing, notebook-validation

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