Python Package Management with uv

This course uses uv for all Python dependency management. Written in Rust, uv is 10-100x faster than pip and replaces multiple tools, pip, pip-tools, pipx, poetry, pyenv, and virtualenv, with a single binary.

Installing uv

macOS / Linux
Windows
Homebrew

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

brew install uv

Inside the course Docker containers, uv is already installed. You only need to install it locally if you are working outside Docker.

Managing Python versions

uv can install and manage Python versions directly, no need for pyenv or system package managers:

# Install a specific Python version
uv python install 3.12

# Pin the Python version for your project
uv python pin 3.12

# List installed versions
uv python list

Virtual environments

uv creates and manages virtual environments:

# Create a virtual environment
uv venv

# Create with a specific Python version
uv venv --python 3.12

# Create with access to system packages (used in course containers)
uv venv --system-site-packages

The virtual environment is created in .venv/ by default. Activate it with:

source .venv/bin/activate

Do not commit the .venv folder to your GitHub repo. The repository’s .gitignore already excludes it.

Installing packages

uv provides a pip-compatible interface for installing packages:

# Install a package
uv pip install numpy

# Install from pyproject.toml
uv pip install -e .

# Install with extras (e.g., notebooks, dev)
uv pip install -e ".[notebooks]"

# Install with a constraints file
uv pip install -e . --constraint constraints.txt

Project management

For projects with a pyproject.toml (like the course repository), uv provides higher-level commands:

# Add a dependency to the project
uv add pandas

# Add a dev dependency
uv add --dev pytest

# Lock dependencies (creates uv.lock)
uv lock

# Sync environment to match the lockfile
uv sync

# Run a script in the project environment
uv run python train.py

The uv.lock file is a cross-platform lockfile that ensures reproducible installs across machines and operating systems.

Course workflow

Inside the course Docker container, dependencies are pre-installed. The typical workflow is:

# Set up the environment (first time)
make start

# Install the package with notebook extras
make install-notebooks

# Or manually:
uv pip install -e ".[notebooks]"

If you need to add a package for your assignment or project:

# Inside the container
uv pip install <package>

Why uv over pip or conda

	uv	pip	conda
Speed	10-100x faster	Baseline	Slower
Lockfiles	Cross-platform `uv.lock`	No built-in lockfile	`environment.yml` (not locked)
Python management	Built-in (`uv python install`)	Requires pyenv or system packages	Built-in
Virtual envs	Built-in (`uv venv`)	Requires virtualenv	Built-in
Disk usage	Global cache, deduplication	Per-environment copies	Large per-environment copies
NVIDIA containers	Compatible	Compatible	Conflicts with pre-installed packages

Avoid conda environments in this course. They conflict with the optimized NVIDIA containers and create dependency resolution issues with pre-installed PyTorch packages.

Useful commands reference

Command	Description
`uv pip install <pkg>`	Install a package
`uv pip install -e ".[extras]"`	Install project with extras
`uv pip compile pyproject.toml`	Generate locked requirements
`uv pip sync requirements.txt`	Sync environment to requirements
`uv add <pkg>`	Add a dependency to `pyproject.toml`
`uv lock`	Create/update the lockfile
`uv sync`	Sync environment to lockfile
`uv run <command>`	Run a command in the project environment
`uv venv`	Create a virtual environment
`uv python install <version>`	Install a Python version
`uv python pin <version>`	Pin Python version for the project
`uv tool run <tool>`	Run a tool in an ephemeral environment

For the full documentation, see docs.astral.sh/uv.

Edit this page on GitHub or file an issue.

Semester

Development Environment

Guides

Python Package Management with uv

Installing uv

Managing Python versions

Virtual environments

Installing packages

Project management

Course workflow

Why uv over pip or conda

Useful commands reference

​Installing uv

​Managing Python versions

​Virtual environments

​Installing packages

​Project management

​Course workflow

​Why uv over pip or conda

​Useful commands reference

Installing uv

Managing Python versions

Virtual environments

Installing packages

Project management

Course workflow

Why uv over pip or conda

Useful commands reference