UV for Python

01 / Why It Exists

The problem uv solves

⚡ Speed

pip resolves dependencies one-by-one in Python. uv is written in Rust and resolves everything in parallel — typically 10–100× faster on fresh installs.

🔒 Reproducibility

pip + requirements.txt can drift across machines. uv uses a lockfile (uv.lock) that pins every transitive dependency to an exact version and hash.

🧰 One Tool

pip, virtualenv, pyenv, pip-tools — uv replaces all of them. One binary, one mental model.

📦 Modern packaging

uv understands pyproject.toml natively — the new standard for Python projects, replacing setup.py and requirements.txt.

02 / Mental Model

How to think about uv

💡

Key insight: In the pip world, the environment IS the project. In the uv world, the project defines what the environment should be. uv creates and manages the environment for you from a declarative spec.

The three files you need to know

my-project/

pyproject.toml ← What your project needs (you edit this)

uv.lock ← Exact pinned versions of everything (auto-generated, commit this)

.venv/ ← The actual environment (auto-managed, don't commit)

notebooks/

src/

Concept mapping: pip → uv

requirements.txt → pyproject.toml (the "what I want" file)
pip freeze > requirements.txt → uv.lock (auto-generated lockfile, much more reliable)
virtualenv / venv → uv creates and manages .venv automatically
pyenv → uv python — uv can download and manage Python versions
pip-tools / pip-compile → baked into uv natively
conda environments → uv environments (note: uv does not handle non-Python/C deps like conda does)

The dependency declaration split

pyproject.toml says "I need numpy ≥ 1.24" — loose, human-maintained constraints
uv.lock says "we are using numpy 1.26.4 with this exact hash" — exact, machine-generated
This split is what makes environments reproducible across your whole team and CI

03 / Installation

Getting uv installed

bash — macOS / Linux

# One-liner installer (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via Homebrew (macOS)
brew install uv

# Verify
uv --version

PowerShell — Windows

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

No Python required — uv is a standalone binary, it doesn't need Python to install
Self-updating — run uv self update to get the latest version
Works great inside Docker, CI (GitHub Actions, etc.), and conda-managed base environments

04 / Project Structure

Starting or adopting a project

Start a brand new project

bash

uv init my-project
cd my-project

This creates a pyproject.toml with sensible defaults. Look inside it — it's readable and editable by hand.

What pyproject.toml looks like

pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "numpy>=1.24",
    "pandas>=2.0",
    "scikit-learn",
    "jupyter",
]

# Optional: dev/test tools kept separate
[dependency-groups]
dev = [
    "pytest",
    "ruff",
]

dependencies — packages your project always needs
dependency-groups — optional groups (dev, test, docs) — not installed by default in production
Version constraints here are loose — the lockfile handles the exact pins

05 / Core Commands

Commands and what they actually do

Command	What it does	pip equivalent
`uv init`	Scaffold a new project with pyproject.toml	manual setup
`uv add numpy`	Add a dependency → updates pyproject.toml + uv.lock + installs it	pip install numpy + manual edit
`uv add --dev pytest`	Add to dev group only	pip install pytest + manual edit
`uv remove numpy`	Remove a dependency and clean up lockfile	pip uninstall + manual edit
`uv sync`	Make the .venv exactly match uv.lock (install missing, remove extra)	pip install -r requirements.txt
`uv sync --group dev`	Sync + include the dev dependency group	pip install -r dev-requirements.txt
`uv lock`	Regenerate uv.lock from pyproject.toml without installing	pip-compile
`uv run python script.py`	Run a command inside the project's environment (auto-syncs first)	source .venv/bin/activate && python script.py
`uv run jupyter lab`	Launch Jupyter inside the environment	source .venv/bin/activate && jupyter lab
`uv python install 3.12`	Download and manage Python version	pyenv install 3.12
`uv python pin 3.12`	Set default Python version for this project	pyenv local 3.12
`uv pip install numpy`	Drop-in pip replacement (no lockfile, for scripts/quick use)	pip install numpy

✦

uv run is your friend. Instead of activating the virtualenv manually, just prefix your commands with uv run. It activates, syncs if needed, runs, and exits cleanly. No more "why is the wrong python in my PATH" confusion.

06 / Daily Workflow

How a typical day looks

Clone or open project

Pull the repo. It has pyproject.toml and uv.lock checked in.

git clone https://github.com/org/project && cd project

Sync the environment

uv reads the lockfile and builds an identical .venv. Takes seconds.

uv sync                    # production deps only
uv sync --group dev        # include dev tools too

Add a new package

You decide you need lightgbm. Add it — pyproject.toml and uv.lock are updated automatically.

uv add lightgbm

Work — run scripts, notebooks, tests

Use uv run to run things inside the environment without activating it.

uv run jupyter lab
uv run python train.py
uv run pytest

Commit the lockfile

Always commit uv.lock. This is what makes the environment reproducible for teammates and CI.

git add pyproject.toml uv.lock
git commit -m "add lightgbm"

07 / Migration

Moving an existing pip project to uv

bash — step by step

# Step 1 — in your existing project dir, initialize uv
uv init --no-package     # --no-package = don't treat this as a library

# Step 2 — import your existing requirements.txt
uv add -r requirements.txt

# Step 3 — (optional) import dev requirements
uv add --group dev -r requirements-dev.txt

# Step 4 — verify everything works
uv sync
uv run python -c "import pandas; print(pandas.__version__)"

Don't delete requirements.txt yet. If other tools (CI, Dockerfiles, teammates) depend on it, keep it around. You can also export: uv export --format requirements-txt > requirements.txt

Updating packages

Task	Command
Update a single package	`uv add numpy --upgrade`
Update all packages	`uv lock --upgrade` then `uv sync`
See what's outdated	`uv tree --outdated`
Show dependency tree	`uv tree`

08 / Python Versions

Managing Python versions (replacing pyenv)

uv can download and manage Python interpreters — no separate pyenv needed
Python versions are stored in uv's own cache, not system-wide
You pin the Python version per-project in pyproject.toml or a .python-version file

bash

# See what Python versions are available
uv python list

# Install a specific version
uv python install 3.12

# Pin this project to Python 3.12
uv python pin 3.12      # creates .python-version file

# Create environment with a specific Python
uv sync --python 3.12

✦

Tip: If you set requires-python = ">=3.11" in pyproject.toml, uv will automatically find or download a compatible Python when syncing. You rarely need to think about this manually.

09 / Jupyter & DS Stack

Using Jupyter and the data science stack

Setup for a typical DS project

bash

# Start a new DS project
uv init my-analysis && cd my-analysis

# Add the core stack
uv add numpy pandas scikit-learn matplotlib seaborn

# Add Jupyter as a dev tool (you don't ship notebooks to prod)
uv add --group dev jupyterlab ipykernel

# Register the kernel so Jupyter sees your environment
uv run python -m ipykernel install --user --name=my-analysis

# Launch
uv run jupyter lab

GPU / CUDA packages (PyTorch, JAX)

uv handles most PyPI packages including GPU builds
Specify the CUDA index for PyTorch just like you would with pip:

bash

# PyTorch with CUDA 12.1
uv add torch torchvision --index https://download.pytorch.org/whl/cu121

# Or pin it in pyproject.toml under [[tool.uv.index]]

conda vs uv: If your workflow relies on non-Python system libraries installed via conda (CUDA toolkit, MKL, etc.), uv doesn't replace conda for that layer. A common pattern is: conda for system libs → uv inside the conda env for Python packages.

10 / Gotchas & Tips

Things that trip people up

Common gotchas

Don't use pip inside a uv project. Running pip install X inside the .venv works but bypasses the lockfile — your environment will silently drift from uv.lock.
uv.lock is machine-generated. Never manually edit it. If you want to change deps, edit pyproject.toml and run uv sync.
Activating the venv is optional. uv run handles it. But if you need to activate manually: source .venv/bin/activate (macOS/Linux) or .venv\Scripts\activate (Windows).
uv add updates pyproject.toml immediately. If you change your mind, use uv remove — don't manually delete from the file without re-running uv sync.

Handy shortcuts

Situation	Command
Quick one-off script, no project	`uv run --with pandas python script.py`
See what's installed	`uv pip list`
Export to requirements.txt format	`uv export --format requirements-txt`
Run a tool without installing it	`uv tool run ruff check .` (or just `uvx ruff check .`)
Install a global CLI tool	`uv tool install ruff`
Check environment is healthy	`uv sync --check`

What to commit vs ignore

Commit: pyproject.toml — your dependency declarations
Commit: uv.lock — the exact pinned environment (this is the point!)
Ignore: .venv/ — always regenerate with uv sync
Ignore: .python-version is optional — commit it if you want to enforce a specific Python for the whole team

.gitignore

.venv/
__pycache__/
*.pyc
.ipynb_checkpoints/