Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 39 ยท Notebooks and Kernels

Choosing and Managing Kernels

Register a virtual environment as a Jupyter kernel with ipykernel, list and remove kernelspecs, read kernel.json, and add kernels for R, Julia, Bash and JavaScript.

One Jupyter installation can offer many kernels: Python 3.11 and 3.12, a project-specific environment with its own libraries, R, Julia, even Bash. Each appears as a choice in the Launcher and in Kernel โ†’ Change Kernel. This lesson teaches you how kernels are described on disk, how to make a virtual environment show up as a kernel, and how to add kernels for other languages.

Commands here run on your own machine (they change what is installed), so they are shown as read-only code. The runnable stand-ins read and generate the same kernel.json files and mimic the lookup that Jupyter performs.

What is a kernelspec?

A kernelspec is a small folder that tells Jupyter how to start a kernel. It contains a file named kernel.json and optionally logo images. Jupyter looks for kernelspecs in a list of directories (user folder, environment folder, system folder). List what it finds:

Terminal
jupyter kernelspec list

Typical output has one line per kernel with its name and path, such as python3 pointing into the active environment. A kernel.json for Python looks like this:

JSON
{
  "argv": [
    "/home/ana/.venv/bin/python",
    "-m", "ipykernel_launcher",
    "-f", "{connection_file}"
  ],
  "display_name": "Python 3 (ipykernel)",
  "language": "python",
  "metadata": { "debugger": true }
}
  • argv is the command that starts the kernel. is replaced by a temporary file with ports and keys that connect the kernel to the server.
  • display_name is what you see in menus.
  • language is used to pick syntax highlighting and, in the file's metadata, the language of the notebook.

The folder name (python3) is the kernel name that is saved inside the notebook (kernelspec.name; see The .ipynb file format).

Python Stand-in: read a kernel.json and build the launch command

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Make a virtual environment available as a kernel

The usual situation: you made .venv for a project, installed pandas and matplotlib there, but the Jupyter you launched uses another Python. The robust fix is to install ipykernel in the project's environment and register it:

Terminal
source .venv/bin/activate                         # or the Windows equivalent
python -m pip install ipykernel pandas matplotlib
python -m ipykernel install --user --name my-project --display-name "Python (my-project)"

The three options matter:

Option Meaning
--user Installs the kernelspec into your user folder, no admin rights needed.
--name The kernel's internal name (no spaces). Notebooks store this.
--display-name The label in menus. Make it recognisable.

Refresh the browser and my-project appears in the Launcher. Choose it when creating a notebook, or switch an existing notebook with Kernel โ†’ Change Kernel.

A simpler alternative is to install jupyterlab itself into every project environment and launch from there; then the default python3 kernel is already the right one. If you use conda, the package nb_conda_kernels (installed next to Jupyter) lists every conda environment that has ipykernel as a kernel automatically.

Removing and updating kernels

Terminal
jupyter kernelspec list              # see names and paths
jupyter kernelspec remove my-project # unregister (does not delete the environment)

Registering a kernel never copies the environment; the kernelspec just points at a Python. If you delete or move the environment, the kernel fails to start ("Kernel died" or "no such file"). Fix by removing the stale spec and registering again.

Stand-in: how Jupyter finds a kernel

When you open a notebook it asks for kernelspec.name. If that name is not installed, Jupyter offers a choice. This stand-in imitates the lookup order (the first match wins, user folder before system folder is the usual order):

Python Stand-in: look up a kernel by name

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Kernels for other languages

Because a kernel is just a program that speaks the messaging protocol, many languages have one. Typical installs (all read-only here, run them locally):

Terminal
# R: in an R session
#   install.packages("IRkernel"); IRkernel::installspec()

# Julia: in a Julia session
#   using Pkg; Pkg.add("IJulia")

# Bash
python -m pip install bash_kernel
python -m bash_kernel.install

# JavaScript and TypeScript with Deno
deno jupyter --install

Other families exist for Scala, Java (JJava, IJava), C++ (xeus-cpp), SQL, Rust (evcxr), Ruby and many more. A notebook is tied to one kernel, so mixing languages in the same notebook needs special tools; the common workaround is magics that call another language (see Line and cell magics).

Add your own kernel

Activate Your project environment
Install ipykernel in that env
Register python -m ipykernel install
Choose Pick it in the Launcher

Four steps, once per environment.

1 / 2

Generating a kernelspec yourself

Sometimes you want a kernel that starts Python with special settings, for example a fixed environment variable. You can write the kernel.json by hand. A tool for that is easy to imagine:

Python Stand-in: generate a kernel.json with an environment variable

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Save such a file as kernel.json inside a folder named for the kernel, within one of the directories shown by jupyter --paths under data, then check it appears in jupyter kernelspec list.

Troubleshooting

Problem What to do
Kernel starts then dies Run the argv command in a terminal to see the Python error; often ipykernel is missing in that environment.
Menu shows a kernel you deleted jupyter kernelspec remove NAME.
Two kernels with the same display name Give each a distinct --display-name.
Wrong packages in the notebook Run import sys; print(sys.executable) in a cell; compare with the environment you expected.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a kernelspec?

    A kernelspec describes how to launch a kernel: the command, display name and language.
  2. 2. Which command registers the active virtual environment as a kernel for your user?

    ipykernel's install command writes a kernelspec that points at the Python that runs it.
  3. 3. You delete a virtual environment that was registered as a kernel. What happens?

    The kernelspec only stores a path; it does not manage the environment.
  4. 4. How many kernels is one notebook attached to at a time?

    A notebook runs against a single kernel, which determines its language and available packages.

Summary

  • A kernelspec (folder with kernel.json) tells Jupyter how to launch a kernel; list them with jupyter kernelspec list.
  • Register a project environment with python -m ipykernel install --user --name NAME --display-name LABEL.
  • Remove stale kernels with jupyter kernelspec remove NAME.
  • Kernels for R, Julia, Bash, Deno and many other languages exist.
  • A notebook is tied to one kernel, saved by name in its metadata.
  • When imports fail, print sys.executable to see which Python the kernel runs.

Next: Restart, interrupt and debug