Link copied

uv + Jupyter in VS Code: ipykernel Setup and Kernel Selection

If your issue is “uv environment does not appear as a Jupyter kernel in VS Code”, this is the quick path:

  1. Install ipykernel in your uv project
  2. Register the kernel with ipython kernel install
  3. Select that kernel from VS Code notebook UI

This guide shows each step with screenshots and troubleshooting.

What you’ll learn

  • Flow for using a uv venv in Jupyter
  • What ipykernel does and how to register a kernel
  • How to select the kernel in VS Code
  • What to check if the kernel doesn’t appear

Prerequisites

Environment

  • macOS Sequoia 15.5
  • VS Code
  • zsh 5.9 (arm64-apple-darwin24.0)

1. Create a project

uv init projectname
cd projectname

2. Add Jupyter (ipykernel) and register a kernel

uv add --dev ipykernel
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=KERNEL_NAME

KERNEL_NAME can be anything (e.g. my-uv-env).

To run Jupyter Lab locally:

uv run --with jupyter jupyter lab

3. Create an .ipynb

In VS Code, run Create: New Jupyter Notebook from the command palette.

New notebook

4. Select the kernel

With the notebook open, use the kernel picker (top right) and choose the kernel you registered in step 2.

Kernel picker
  • If it’s missing: Select Another Kernel… → Jupyter Kernel → your kernel name.
Kernel list
If the kernel still doesn’t show

Select Another Kernel… → Jupyter Kernel → pick the kernel you created.

Jupyter Kernel path

5. Sanity check

Run:

import sys

print(f"Python version: {sys.version}")
print(f"Virtual environment: {sys.prefix}")
Test run

If you see your .venv path, the notebook is using the uv environment.

sys.prefix check

Troubleshooting

Kernel not in the list

List registered kernels:

uv run jupyter kernelspec list

Pick the matching KERNEL_NAME in VS Code under Select Another Kernel….

Remove a kernel

uv run jupyter kernelspec uninstall KERNEL_NAME

Common mistakes

  • Installing ipykernel outside the uv project environment
  • Registering a kernel but selecting a different one in VS Code
  • Forgetting to reopen kernel picker after registering a new kernelspec

Summary

  • Add ipykernel with uv, run ipython kernel install, then pick that kernel in VS Code’s Jupyter UI.
  • If it’s missing, run jupyter kernelspec list and reconnect via Jupyter Kernel.

References