nbconvert "ModuleNotFoundError" inside the kernel in CI

When nbconvert executes a notebook it starts a Jupyter kernel, and that kernel may point at a different Python interpreter than the one your CI step ran pip install against. Imports that succeed in the shell then fail inside the kernel with ModuleNotFoundError.

What this error means

jupyter nbconvert --to notebook --execute fails with a CellExecutionError whose traceback ends in "ModuleNotFoundError: No module named 'X'", even though pip show X reports it is installed.

nbclient.exceptions.CellExecutionError: An error occurred while executing the following cell:
------------------
import pandas as pd
------------------
ModuleNotFoundError: No module named 'pandas'

Common causes

The kernelspec points at a different interpreter

The notebook's embedded kernel name maps to a Python (often the system one) that does not have your packages, while pip installed into the venv on PATH.

Packages installed into a venv the kernel does not use

CI activated a venv for pip install but the registered python3 kernel resolves elsewhere, so the kernel cannot see those packages.

How to fix it

Register a kernel for the active interpreter

1. Install ipykernel into the same Python you installed dependencies into.
2. Register that interpreter as a named kernel.
3. Run nbconvert against that kernel name.

python -m pip install ipykernel
python -m ipykernel install --user --name ci-kernel
jupyter nbconvert --to notebook --execute --ExecutePreprocessor.kernel_name=ci-kernel notebook.ipynb

Install dependencies into the kernel Python

Confirm which interpreter the kernel uses and install requirements into exactly that one.

jupyter kernelspec list
python -m pip install -r requirements.txt

How to prevent it

• Register an explicit kernel for your CI interpreter and pass it to nbconvert.
• Install dependencies with python -m pip into the same Python the kernel uses.
• Avoid relying on the notebook's saved kernel name matching the CI environment.

Related guides