nbclient

nbclient is a client library for programmatically executing Jupyter notebooks. It runs a notebook’s cells against a Jupyter kernel in a controlled execution context, updating the notebook document in place with the resulting outputs, execution counts, and any errors.

Extracted from the execution core of nbconvert, nbclient provides a clean NotebookClient API (plus convenience helpers) for automation, testing, and reproducibility workflows. It is a foundational dependency for tools like papermill, nbconvert, and Jupyter Book that need to run notebooks headlessly in pipelines and CI.

What You Get

• A NotebookClient class that executes notebook cells against a managed Jupyter kernel
• In-place population of cell outputs, execution counts, and error information
• Configurable timeouts, error handling, and kernel management for robust runs
• A command-line entry point plus async support for programmatic execution

Common Use Cases

• Running notebooks headlessly in CI to verify they execute without errors
• Powering parameterized notebook execution tools such as papermill
• Regenerating notebook outputs as part of documentation and reporting builds

Under The Hood

Architecture - The heart of the package is nbclient/client.py, which defines NotebookClient (a Traitlets-configurable object). It starts a kernel via jupyter_client’s kernel manager, iterates over the notebook’s code cells executing each against the kernel, listens on the message channels to collect outputs and update the notebook model, and raises rich errors from exceptions.py (such as CellExecutionError) on failure. output_widget.py handles widget outputs, jsonutil.py/util.py provide serialization and async helpers, and cli.py exposes a command-line interface.

Tech Stack - It is pure Python built on the Jupyter protocol stack: nbformat for the notebook model, jupyter_client and traitlets for kernel management and configuration, and async I/O for message handling. It is packaged via a modern pyproject build and ships type information (py.typed).

Code Quality - The repository includes a focused tests/ suite covering the client, CLI, and utilities with shared fixtures (conftest.py), CI via GitHub Actions, and Read the Docs documentation. As a mature, community-adopted Jupyter subproject with a high fork ratio, it reflects solid engineering and stability.

API Design - The primary API is ergonomic: construct NotebookClient(nb, timeout=..., kernel_name=...) and call execute(), or use the module-level execute(nb) helper for the common case. Behavior is tuned through Traitlets configuration (timeouts, allow_errors, kernel selection), and both sync and async entry points are provided, so it scales from a one-liner to fine-grained control.