agent executed cells against the base kernel instead of the venv: wrong packages

TL;DR

The notebook's kernel metadata names a kernel, but agents often launch execution with whatever python3 kernel is default, which is the base environment, so imports resolve to the wrong packages or fail entirely. Set the kernel explicitly (notebook metadata kernelspec, or the --kernel equivalent in your runner) to the project's venv kernel before executing. Verify by printing the interpreter path in the first cell: it must be the venv's Python, not the base one.

agent executed cells against the base kernel instead of the venv: wrong packages

Use this when

• Cells fail with ModuleNotFoundError for packages that are installed in the project venv.
• Imports succeed but the package versions are wrong (base env versions, not project versions).
• An agent's automated execution behaves differently from the developer's interactive run.

Not for this skill when

• The kernel fails to start at all. That is a broken kernelspec, a different fix.
• Packages are missing even in the correct venv. That is an incomplete environment, not a kernel mix-up.

Steps

1. Prove the mix-up: run a cell that prints the interpreter path and one package version. Expected: the path points at the base environment, confirming the wrong kernel.
2. List kernels: jupyter kernelspec list and identify the venv's kernel by its path. Expected: a kernel whose argv points at the venv's Python.
3. If the venv has no kernel registered, create one from the venv's Python: [venv-python] -m ipykernel install --user --name [project] --display-name "[project]". Expected: the new kernel appears in the list with the venv path.
4. Set the notebook's kernel metadata to the venv kernel (Kernel menu, or edit the kernelspec in the notebook metadata). Expected: the notebook file names the venv kernel.
5. Make the agent pass the kernel explicitly at execution time instead of relying on defaults or file metadata. Expected: the runner command or API call names the venv kernel.
6. Re-run with a canary first cell that asserts the interpreter path and fails loudly otherwise. Expected: any future kernel mix-up fails fast on cell one instead of producing wrong results silently.

Tool compatibility

ipykernel 6.x; venv/virtualenv/conda environments; nbclient and papermill runners; Python 3.9+.

Variant phrasings

notebook ran with wrong kernel packages missing

The symptom phrasing. Pin the venv kernel and add a canary cell.

agent used base python instead of venv kernel

The agent phrasing. Pass the kernel explicitly at execution time.

jupyter executed with system kernel not virtualenv

The environment phrasing. Register the venv as a kernel and select it.

Why it happens

Kernel selection has too many defaults: the notebook file's metadata, the runner's default kernel, and the UI's last-used kernel can all disagree, and agents typically control none of them explicitly. The base environment almost always has a working python3 kernel, so execution 'succeeds' in the sense that cells run, but against the wrong package set, producing wrong versions or confusing import errors far from the real cause. Making the kernel an explicit, verified input (with a canary cell that fails fast) turns a silent wrong-environment run into either a correct run or an immediate loud failure.

Edge cases / pitfalls

• Notebook metadata set interactively can be overwritten by the next agent run that does not pass a kernel. Prefer the explicit runner argument as the source of truth.
• Two venvs with similar names (project vs project-old) are easy to confuse in the kernel list. Use distinct display names and verify by path, not by name.
• The canary cell must run FIRST. An agent that resumes mid-notebook skips the guard; enforce top-to-bottom execution.
• Conda env renames break the registered kernel path silently. Re-register the kernel after any env rename.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst9jEXsLeLRnsG4hBF3_A