Article Overview

This article describes how to add/remove kernels for uv virtual environments.

Assumed Scenario

There is a uv-managed Python repository called my-python-repo, and we want to create a kernel for this repository's library environment to work in Jupyter Notebook.

Kernel Addition Steps

1. Clone my-python-repo

First, let's get my-python-repo.

git clone git@xxx.org:myorg-dev/my-python-repo.git

2. Create Virtual Environment from uv.lock

After cd into the cloned my-python-repo, you can create a virtual environment based on uv.lock by running uv sync.

uv sync

This creates a venv virtual environment (.venv directory) based on uv.lock. We just need to create a kernel linked to this virtual environment.

3. Add ipykernel to Virtual Environment for Jupyter Kernel Recognition

Jupyter requires ipykernel to recognize the virtual environment as a kernel.

uv add --dev ipykernel

4. Register Virtual Environment as Jupyter Kernel

As an example, we'll register a kernel with the name Python3.13.2-my-python-repo-new-feature.

uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name="Python3.13.2-my-python-repo-new-feature"

You can confirm it's been added by checking the kernel list with the following command:

jupyter kernelspec list

Check kernel.json and verify that the destinations of python and VIRTUAL_ENV are as expected.

• The first element of argv points to python in .venv/bin

• VIRTUAL_ENV points to the .venv created by uv

$ cat ~/.local/share/jupyter/kernel/python3.13.2-my-python-repo-new-feature/kernel.json
{
 "argv": [
  "/home/xxx/workspace/xxx_notebooks/my-python-repo/.venv/bin/python3",
  "-m",
  "ipykernel_launcher",
  "-f",
  "{connection_file}"
 ],
 "display_name": "Python3.13.2-my-python-repo-new-feature",
 "language": "python",
 "metadata": {
  "debugger": true
 },
 "env": {
  "VIRTUAL_ENV": "/home/xxx/workspace/xxx_notebooks/my-python-repo/.venv"
 }

5. Open Jupyter Notebook and Use the Kernel

When you open Jupyter Notebook, the kernel has been added, so select it and start working.

Kernel Removal Steps

To remove a kernel, do the following:

# Check kernel list
$ jupyter kernelspec list

# Remove myenv kernel
$ jupyter kernelspec uninstall myenv

How to Add Libraries in Kernels Linked to uv Virtual Environment

By running !uv add in a notebook cell as shown below, you can add libraries to the uv virtual environment and immediately import them.

!uv add requests

Alternatively, instead of from the notebook, you can go to the location where the uv virtual environment is in the terminal

uv add requests

and add normally like this, which will add the library to the kernel. In this case too, you can immediately import it on the notebook side.

Summary

I think it's good to value environment reproducibility and utilize uv even in Jupyter Notebook.

References

https://docs.astral.sh/uv/guides/integration/jupyter/