Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt

Use this file to discover all available pages before exploring further.

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: 
uv venv --seed
uv pip install pydantic jupyterlab
.venv/bin/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

Build docs developers (and LLMs) love

Get started for freeTalk to us