Skip to main content
Integrate uv with Jupyter notebooks for interactive Python development, data analysis, and visualization with full project environment support.

Using Jupyter in a Project

Run Jupyter with access to your project’s virtual environment:
This starts Jupyter Lab at http://localhost:8888/lab with access to your project’s dependencies.

Importing Project Dependencies

Within a notebook, you can import your project’s modules directly:

Creating a Kernel

For projects requiring package installation from notebooks, create a dedicated kernel:
1

Add ipykernel as dev dependency

2

Create the kernel

Replace project with your desired kernel name.
3

Start Jupyter

4

Select kernel in notebook

When creating a new notebook, select the project kernel from the kernel dropdown menu.

Installing Packages with a Kernel

Once the kernel is configured, install packages from within notebooks:
Both commands make the package immediately available:

Without a Kernel

You can still install packages without creating a kernel, but with some caveats:

Using uv add

Using uv pip install

Without a kernel, !uv pip install installs packages into Jupyter’s isolated environment, not your project. These packages may disappear when Jupyter restarts.

Using pip Magic with Seed Environment

For notebooks using the %pip magic:
1

Create seeded virtual environment

2

Start Jupyter

3

Use pip magic in notebooks

Packages installed with %pip won’t be reflected in pyproject.toml or uv.lock.

Standalone Jupyter

Run Jupyter without a project for ad-hoc analysis:
This creates an isolated Jupyter environment unrelated to any project.

Non-Project Virtual Environments

Use Jupyter in a virtual environment without a project structure:
Install packages using either method:

VS Code Integration

Use Jupyter notebooks within VS Code with uv-managed projects:
1

Create project with ipykernel

2

Open in VS Code

3

Create notebook

Open the command palette and select “Create: New Jupyter Notebook”.
4

Select kernel

When prompted for a kernel, choose “Python Environments” and select your virtual environment:
  • macOS/Linux: .venv/bin/python
  • Windows: .venv\Scripts\python

Installing Packages in VS Code

For full environment manipulation, add uv as a dev dependency:
Then use in notebooks:
VS Code requires ipykernel in the project environment. If you prefer not to add it as a dev dependency, install it directly: uv pip install ipykernel

Common Workflows

Data Science Project

Quick Exploration

Reproducible Research

Best Practices

  • Use kernels for projects requiring package installation from notebooks
  • Pin Jupyter version in pyproject.toml for reproducibility
  • Use uv add to ensure dependencies are tracked in your project
  • Avoid %pip magic unless using a seeded environment
  • Add ipykernel as a dev dependency for VS Code compatibility
  • Create kernel per project to avoid environment conflicts