Jupyter Integration

Use uv with Jupyter notebooks for interactive computing and data analysis

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:

uv run --with jupyter jupyter lab

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:

import requests  # Imports from project's virtual environment
import pandas as pd
from myproject import my_module

Creating a Kernel

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

1. Add ipykernel as dev dependency

   uv add --dev ipykernel
   
2. Create the kernel

   uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=project
   

   Replace project with your desired kernel name.

3. Start Jupyter

   uv run --with jupyter jupyter lab
   
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:

# Add to project dependencies (updates pyproject.toml and uv.lock)
!uv add pydantic

# Install to virtual environment only (no project updates)
!uv pip install pydantic

Both commands make the package immediately available:

import pydantic

Without a Kernel

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

Using uv add

# Modifies project environment and files
!uv add pydantic
import pydantic  # Works immediately

Using uv pip install

# Installs to Jupyter's environment (temporary)
!uv pip install pydantic

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

   uv venv --seed
   
2. Start Jupyter

   uv run --with jupyter jupyter lab
   
3. Use pip magic in notebooks

   %pip install requests
   import requests
   

   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:

uv tool run jupyter lab

This creates an isolated Jupyter environment unrelated to any project.

Non-Project Virtual Environments

Use Jupyter in a virtual environment without a project structure:

macOS and Linux

uv venv --seed
uv pip install pydantic jupyterlab
.venv/bin/jupyter lab

Windows

uv venv --seed
uv pip install pydantic jupyterlab
.venv\Scripts\jupyter lab

Install packages using either method:

!uv pip install requests
# or
!pip install requests

VS Code Integration

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

1. Create project with ipykernel

   uv init project
   cd project
   uv add --dev ipykernel
   
2. Open in VS Code

   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:

uv add --dev uv

Then use in notebooks:

# Add to project dependencies
!uv add pydantic

# Install without updating project files
!uv pip install pydantic

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

# Set up project
uv init data-analysis
cd data-analysis
uv add pandas numpy matplotlib seaborn
uv add --dev ipykernel jupyter

# Create kernel
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=data-analysis

# Start Jupyter
uv run jupyter lab

Quick Exploration

# Create temporary environment
uv venv --seed
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install tools
uv pip install jupyterlab pandas

# Start Jupyter
jupyter lab

Reproducible Research

# Project with locked dependencies
uv init research-project
cd research-project
uv add pandas numpy scipy matplotlib jupyter ipykernel

# Lock dependencies
uv lock

# Share with collaborators (they run)
uv sync --locked
uv run jupyter lab

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