Kernels and environments

Picking the wrong kernel is the number one cause of 'it works in the terminal but not in the notebook'.

A kernel is the process that runs a notebook's code and holds its variables. The front end sends code to it and receives outputs back. For Python the kernel is ipykernel, built on IPython; other kernels exist for R (IRkernel), Julia (IJulia), JavaScript, Rust, Go and many more.

Each kernel runs with one specific Python interpreter, and therefore one environment. A kernelspec (a small kernel.json file) tells Jupyter how to start it. To make a project's virtual environment available in a Jupyter installed elsewhere:

.venv/bin/python -m pip install ipykernel
.venv/bin/python -m ipykernel install --user --name myproj --display-name "Python (myproj)"

Then pick "Python (myproj)" from the kernel selector. jupyter kernelspec list shows registered kernels, and jupyter kernelspec uninstall myproj removes one. In a notebook, import sys; sys.executable tells you which interpreter is running.

Kernel controls:

Interrupt (I, I or the stop button) raises KeyboardInterrupt in the running cell, useful for runaway loops.
Restart clears all variables and imports; use it after upgrading a package or when state is confusing.
If a kernel dies (often from running out of memory or a crashing C extension), all state is lost and you must rerun cells.

Install packages from a notebook with %pip install package: the magic always targets the kernel's own environment, unlike !pip, which may use a different pip on your PATH.

Example

# Register a project environment as a kernel
python -m venv .venv
.venv/bin/python -m pip install -q ipykernel
.venv/bin/python -m ipykernel install --user --name myproj \
    --display-name "Python (myproj)"

jupyter kernelspec list
#   myproj     /home/me/.local/share/jupyter/kernels/myproj
#   python3    /usr/local/share/jupyter/kernels/python3

cat ~/.local/share/jupyter/kernels/myproj/kernel.json
# {"argv": [".../.venv/bin/python", "-m", "ipykernel_launcher", "-f",
#   "{connection_file}"], "display_name": "Python (myproj)", "language": "python", ...}

jupyter kernelspec uninstall -y myproj

Remember

A kernel is the process that executes code; each uses one interpreter and environment
Register environments with python -m ipykernel install --user --name ...
Use %pip install in notebooks so packages land in the kernel's environment

Watch out for

Running !pip install and installing into a different environment than the kernel uses.

Check yourself

A package imports fine in your terminal's venv but fails in the notebook. What should you check first?

Official docs: ipython.readthedocs.io/en/stable/install/kernel_install.html

Example

Remember

Watch out for

Check yourself

Builds on

Unlocks