Custom Jupyter kernels with uv

What custom kernels are for

A custom Jupyter kernel lets a notebook run with a specific Python environment instead of the default project Python. Use one when a project needs a controlled set of Python packages, a different Python version, or separate environments for different notebooks.

For shared courses or many projects, prefer a runtime image when everyone should start with the same system-wide environment. Use a custom kernel when one project or one notebook needs an isolated Python environment.

Ask Agent to install a kernel

The kernel selector offers agent-assisted installation when it is allowed in this project. Use this when you know the language or environment you need but want help with installation and registration.

1. Open the notebook's kernel selector.
2. Open Install kernels or Install, depending on the selector layout. If no kernels are installed, the installation choices appear with that explanation.
3. Click Agent beside a suggested kernel, or in the Ask Agent row for another kernel.
4. In Install Jupyter Kernel with Agent, edit the request to include the language, version, and packages you need. Select a recent agent session or New agent thread.
5. Choose whether to enable Automatically submit to Agent, then Send. If unchecked, review and send the prepared request from the agent chat.
6. After installation succeeds, refresh the kernel list, select the new kernel, and run a small example.

The agent is asked to inspect the project environment, install the requested kernel, and register its kernelspec. Installation can download packages and modify the project environment. The control depends on the project's kernel installation policy, and success depends on packages and permissions; follow any reported blocker in the chat.

Create a Python kernel with uv

The commands below are for a Linux project using a POSIX shell. Local CoCalc Plus uses your computer's operating system and installed software; interpreter paths and shell commands can differ there.

Open a terminal in the project and install uv if it is not already available:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then create a virtual environment, install ipykernel, and register the environment as a Jupyter kernel:

mkdir -p ~/.venvs
uv venv ~/.venvs/my-analysis --python 3.12
uv pip install --python ~/.venvs/my-analysis/bin/python \
  ipykernel pandas numpy matplotlib
~/.venvs/my-analysis/bin/python -m ipykernel install --user \
  --name my-analysis \
  --display-name "Python (my-analysis)"

Use a short lowercase --name with letters, numbers, dashes, or underscores. The display name is what people see in the notebook kernel selector. Replace 3.12 with python3 or another installed Python version when needed.

Use the kernel in CoCalc

1. Open or create a notebook.
2. Open the kernel selector or Kernel menu.
3. Choose Python (my-analysis).
4. Run a cell that imports a package installed in the environment.

If the kernel does not appear, click Refresh in the kernel selector to reload its list. Check the registered kernelspec and its Python path if it is still missing. If a runtime or tools update requires a project restart, save your work first: a project restart stops its running processes.

Install more packages later

Install packages into the same virtual environment by pointing uv pip at the environment's Python:

uv pip install --python ~/.venvs/my-analysis/bin/python scikit-learn seaborn

Then restart the notebook kernel before importing newly installed packages.

Remove a custom kernel

Remove the Jupyter kernelspec and, if you no longer need it, remove the virtual environment:

jupyter kernelspec uninstall my-analysis
rm -rf ~/.venvs/my-analysis

Why this matters in CoCalc

Custom Jupyter kernels use ordinary kernelspecs backed by Python executables. Humans and agents can inspect, rebuild, and document the environment with terminal tools appropriate to the project's operating system.