Install & Compatibility
Where this runs
tested against v0.11.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.808s · 36.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.9s · import 0.760s · 33MB
34MB installed
● package 34MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NotebookClient
✓ from nbclient import NotebookClient
The primary class for executing notebooks programmatically.
nbformat
✓ import nbformat
Used to load and save notebook objects.
execute
✓ from nbclient import execute
✗ from nbconvert.preprocessors.execute import executenb
The `executenb` function was deprecated and moved from `nbconvert.preprocessors.execute` to `nbclient.execute`. Direct import from `nbclient` is recommended.
This example demonstrates how to create a basic Jupyter notebook programmatically, execute it using `nbclient`, and then save the resulting notebook with its outputs. It also includes cleanup of the temporary files.
import nbformat
import os
from nbclient import NotebookClient
# Create a dummy notebook for execution
notebook_content = {
"cells": [
{
"cell_type": "code",
"source": "a = 1\nb = 2\nprint(a + b)",
"outputs": [],
"execution_count": None
},
{
"cell_type": "code",
"source": "import time\ntime.sleep(0.1)\nprint('Done sleeping')",
"outputs": [],
"execution_count": None
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.10.0"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
input_notebook_path = "my_input_notebook.ipynb"
output_notebook_path = "my_executed_notebook.ipynb"
with open(input_notebook_path, 'w', encoding='utf-8') as f:
nbformat.write(nbformat.from_dict(notebook_content), f)
# Load the notebook
with open(input_notebook_path) as f:
nb = nbformat.read(f, as_version=4)
# Configure and execute the notebook
# Adjust timeout for potentially long-running cells or set to None/-1
client = NotebookClient(nb, timeout=600, kernel_name='python3')
try:
client.execute()
print(f"Notebook '{input_notebook_path}' executed successfully.")
except Exception as e:
print(f"Error executing notebook: {e}")
# Save the executed notebook with outputs
with open(output_notebook_path, 'w', encoding='utf-8') as f:
nbformat.write(nb, f)
print(f"Executed notebook saved to '{output_notebook_path}'.")
# Clean up dummy notebook files
os.remove(input_notebook_path)
os.remove(output_notebook_path)
Debug
Known issues
breakingnbclient has incrementally dropped support for older Python versions. Version 0.10.2 dropped Python 3.8 support, and 0.10.3 dropped Python 3.9 support. Users on these Python versions must upgrade their Python environment to 3.10+ or use an older `nbclient` version.fixUpgrade your Python environment to 3.10 or newer, or pin `nbclient` to a compatible older version (e.g., `<0.10.2` for Python 3.9, `<0.10.0` for Python 3.8).
affects: >=0.10.2
breakingnbclient was extracted from `nbconvert`'s `ExecutePreprocessor`. Code that previously imported `ExecutePreprocessor` or `executenb` from `nbconvert` needs to be updated to use `nbclient` directly.fixMigrate imports from `from nbconvert.preprocessors.execute import ...` to `from nbclient import ...`. For example, `from nbconvert.preprocessors.execute import executenb` should become `from nbclient import execute`.
affects: All versions (since nbclient's inception)
gotchaThe `timeout` parameter in `NotebookClient` defaults to 30 seconds per cell. For notebooks with long-running cells, this can lead to `TimeoutError`. fixWhen initializing `NotebookClient`, explicitly set `timeout` to a higher value (e.g., `timeout=600` for 10 minutes) or set it to `None` or `-1` to disable the timeout entirely.
affects: All versions
breakingAn `AttributeError: metadata` occurs during `nbformat.write`, specifically when `nbformat` attempts to process `cell.metadata` (e.g., in `strip_transient`). This indicates that a notebook cell object within the provided content is malformed and lacks the expected 'metadata' attribute. This often happens when the input dictionary passed to `nbformat.from_dict` does not strictly conform to the `nbformat` specification, where every cell (code, markdown, raw) must have a `metadata` dictionary.fixEnsure that the notebook content (dictionary) provided to `nbformat.from_dict` or similar constructors is valid and adheres to the `nbformat` specification. Specifically, verify that every cell object includes a `metadata` attribute, which should be a dictionary (even if empty). Consider using `nbformat.normalize()` on the notebook object before writing to resolve common structural issues if your `nbformat` version supports it.
affects: All versions where `nbformat` expects well-formed cell objects (observed on Python 3.9)
breakingAn `AttributeError: metadata` occurs when `nbformat` attempts to write a notebook where one or more cell objects are missing the required `metadata` attribute. This typically happens when notebook content is programmatically constructed and does not fully adhere to the `nbformat` schema, which dictates that every cell must include a `metadata` dictionary.fixEnsure that all cell objects within the notebook structure (e.g., passed to `nbformat.from_dict`) explicitly include a `metadata` attribute, even if it's an empty dictionary (e.g., `{'cell_type': 'code', 'source': '...', 'metadata': {}}`). Verify that the notebook content conforms to the `nbformat` schema before writing. affects: All nbformat versions that process notebook content according to the v4 schema (i.e., >=4.0).
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nbformat'
The 'nbformat' package (a dependency of nbclient) is not installed in the Python environment being used, or there's a mismatch between the installed environment and where nbclient is trying to run.
fixEnsure 'nbformat' and 'nbclient' are installed in the active Python environment by running `pip install nbformat nbclient` or `conda install nbformat nbclient`.
nbclient.exceptions.CellExecutionError: An error occurred while executing the following cell:
A cell within the executed Jupyter notebook encountered an unhandled exception during its execution. By default, nbclient stops notebook execution and raises this error.
fixInspect the notebook's saved output or the detailed traceback provided by the error message to debug the specific code in the failing cell. To allow the notebook to continue executing even after an error, initialize `NotebookClient` with `allow_errors=True`.
nbclient.exceptions.CellTimeoutError: A cell timed out while it was being executed, after X seconds.
A specific cell in the notebook exceeded the maximum allowed execution time, which defaults to 30 seconds.
fixIncrease the `timeout` parameter when initializing `NotebookClient` (e.g., `NotebookClient(nb, timeout=600)` for 10 minutes), or set `timeout=None` or `timeout=-1` to disable the timeout for all cells.
RuntimeError: Kernel died before replying to kernel_info
The Jupyter kernel responsible for executing the notebook's code unexpectedly terminated or became unresponsive during startup or execution. This can be caused by resource exhaustion (e.g., memory), unhandled kernel crashes, or issues with the kernel itself.
fixCheck for sufficient system resources (RAM, CPU) if running locally, or increase allocated compute resources if on a cloud platform like Kaggle. Review the notebook's code for operations that might consume excessive resources. Ensure `jupyter_client` and other Jupyter-related packages are up to date.
Upgrade
Version history
0.11.0latest on PyPI · released Jun 5, 2026
Audit
Dependencies
nbformatrequiredRequired for reading and writing Jupyter notebook files.
jupyter_clientrequiredUsed internally by nbclient for managing Jupyter kernels.