Installing Jupyter Kernels

Zasper implements the Jupyter wire protocol, so it runs any language that has a Jupyter kernel. A kernel installed with a kernelspec, for Python, R, Julia, Go, JavaScript or anything else, shows up in the Launcher with nothing to configure.

Step by step: Use R, Julia or Any Kernel.

No Kernel Yet? Let Zasper Set One Up

If Zasper finds no kernel at all, the Launcher says so and offers Set up a Python kernel. Click it and Zasper:

1. creates a .venv folder in your project, with uv if you have it and python3 -m venv if you don’t;
2. installs ipykernel into that .venv;
3. lists it in the Launcher as Python 3.x (.venv).

The setup’s output appears in the Launcher as it runs, and the new kernel shows up when it finishes. The setup runs only in a folder you trust; see Trusted Folders.

Nothing else is touched. Zasper never installs anything on its own when it starts, never installs into your system or Homebrew Python, and never writes a kernelspec. A virtual environment is the one place pip is always allowed. If your project already has a .venv with ipykernel in it, the setup just checks it; if it has a .venv folder with no Python inside, the setup stops and asks you to remove it rather than replace it.

The setup needs a network connection to download ipykernel, and a Python 3 to build the environment from. If uv finds no Python, it downloads one into its own folder.

Supported Kernels

How Zasper Finds Kernels

Zasper lists three kinds of kernel, and the Launcher shows all of them.

Registered kernels. These are the kernels with a kernelspec, the folder holding a kernel.json that python -m ipykernel install, IRkernel::installspec() and the others create. Zasper looks in the same places Jupyter does, in the same order:

• if jupyter is on your PATH, the folders jupyter --paths lists, first;
• the folders in JUPYTER_PATH;
• your own Jupyter folder: ~/Library/Jupyter on macOS, ~/.local/share/jupyter on Linux, %APPDATA%\jupyter on Windows (or JUPYTER_DATA_DIR if you set it);
• the active conda environment or virtualenv, when Zasper is started from a shell with one activated. Inside a virtualenv or a non-base conda environment it comes before your own folder, as Jupyter does, and JUPYTER_PREFER_ENV_PATH decides either way;
• the system: /usr/local/share/jupyter and /usr/share/jupyter, or %PROGRAMDATA%\jupyter;
• on Windows, the Microsoft Store’s Python, whose own folder is read-only, so pip install ipykernel puts the kernel under that Python’s LocalCache folder instead (from 1.1.0);
• Anaconda, Miniconda and Miniforge in your home folder, and on macOS, Homebrew and every Python’s own folder: each version under ~/Library/Python, the Command Line Tools’ Python and the python.org installers;
• every conda environment, active or not, last: the ones listed in ~/.conda/environments.txt, and the envs folders of Anaconda, Miniconda, Miniforge, Mambaforge and micromamba (or MAMBA_ROOT_PREFIX). IRkernel and xeus kernels are usually installed into an environment of their own, and this is where their kernelspecs stay.

When two folders hold a kernel of the same name, the first one wins, as it does in Jupyter. Names are matched without regard to case.

Pythons with ipykernel that were never registered. If a Python on your PATH, your active environment, a conda install or (on macOS) a Homebrew, Command Line Tools or python.org Python has ipykernel installed but no kernelspec, Zasper offers it anyway, the way Jupyter offers its own Python. The first is named python3 when no kernel of that name is installed; the rest are named for their version and origin, such as python3.12-homebrew, and shown as Python 3.12 (Homebrew). Nothing is written to disk for these, so there is nothing to go stale when an environment is deleted. Installing ipykernel into one of them later is noticed without restarting Zasper.

Your project’s own environment. If the folder Zasper is open on has a .venv or venv with ipykernel in it, it is listed first, as Python 3.x (.venv). Its kernel name is project-venv in every project, so a notebook saved on it opens on a collaborator’s own .venv when they clone the same repository. It runs as if the environment were activated, so !pip install in a notebook installs into it. Zasper finds it by reading the folder and does not run anything inside it until you choose it. Until you trust the folder, the Launcher shows it locked and does not run it; see Trusted Folders.

A kernelspec that names a bare python, as ipykernel’s own spec does, runs with the Python that installed it, not whichever python comes first on your PATH. Installing another Python, such as Homebrew’s, does not take your existing kernels away or run them with the wrong interpreter.

The same holds for other languages. A kernelspec inside a conda environment that names a bare command, as conda’s IRkernel does with R, runs that environment’s R, with the environment first on the kernel’s PATH, as if it were activated.

{connection_file}, {resource_dir} and {prefix} are filled in anywhere in a kernelspec’s argv, as Jupyter does, not only as a whole argument.

Viewing Installed Kernels

To check which kernels are registered on your system, run:

$ jupyter kernelspec list
Available kernels:
  deno          /Users/you/Library/Jupyter/kernels/deno
  firstenv      /Users/you/Library/Jupyter/kernels/firstenv
  gonb          /Users/you/Library/Jupyter/kernels/gonb
  ir            /Users/you/Library/Jupyter/kernels/ir
  julia-1.11    /Users/you/Library/Jupyter/kernels/julia-1.11
  ruby3         /Users/you/Library/Jupyter/kernels/ruby3
  python3       /Users/you/Library/Python/3.9/share/jupyter/kernels/python3

This shows registered kernels only. The Launcher also lists unregistered Pythons with ipykernel and your project’s .venv, which this command does not know about.

Installing a Python Kernel

For a plain Python kernel, use Set up a Python kernel in the Launcher, or install ipykernel yourself:

pip install ipykernel

or

pip install jupyter

Setting Up Other Language Kernels

Each of these installs a kernel and registers it with a kernelspec.

R (IRkernel)

Open R and run:

install.packages('IRkernel')
IRkernel::installspec(user = TRUE)

You’ll see an ir kernel appear in Zasper.

Julia (IJulia)

Open the Julia REPL and run:

using Pkg
Pkg.add("IJulia")

The IJulia package automatically registers the kernel.

Go (GoNb)

Install Go, then GoNb and the goimports and gopls tools it uses:

go install github.com/janpfeifer/gonb@latest
go install golang.org/x/tools/cmd/goimports@latest
go install golang.org/x/tools/gopls@latest
gonb --install

The Go kernel will be available in jupyter kernelspec list.

JavaScript (Deno)

Follow the official instructions:

deno jupyter --install

After installing, the Deno kernel will be available for use in Zasper.

Troubleshooting

If a kernel doesn’t appear in Zasper, check jupyter kernelspec list to confirm it’s registered, and make sure you’ve installed ipykernel or the required language-specific runtime.

Zasper reads the kernel list again whenever the Launcher asks for it, so reloading the page picks up a kernel installed while it was running; Check again does the same when the Launcher says there are no kernels. Restart Zasper if you have installed a new version of Python since it started.

A kernelspec whose kernel.json cannot be read, or names no program to run, is left out of the list, and Zasper logs a skipping kernelspec warning saying why.

If a kernel exits on its own, while starting or later, the notebook says so and why, such as The kernel stopped before it was ready: it exited with code 1, with the last lines the kernel printed. Those lines are usually the traceback or error that explains it. Start the kernel again from there or pick another.

A kernel that is slow to start, such as one importing a large environment on a cold disk, is waited for however long it takes.

If Set up a Python kernel fails, its output stays in the Launcher. The usual causes are no network connection, no Python 3 to build the environment from, or a .venv folder that is already there with no Python in it.