Skip to content

uv

A single tool that replaces pip, venv, virtualenv, pip-tools, and pyenv — written in Rust, ~10–100× faster installs, with a built-in lockfile. The modern default for new Python projects.

Table of Contents

Installation / Setup

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.rs | iex"

# Or via package managers
brew install uv            # macOS
winget install astral-sh.uv  # Windows
pip install uv             # anywhere pip works

Verify: uv --version. On first run, uv downloads a managed Python if none matches.

Core Syntax

Environments (replaces venv)

Command What it does
uv venv Create .venv in the current directory
uv venv --python 3.12 Create with a specific Python
uv python install 3.12 Install a managed Python (replaces pyenv)
uv python list List available/managed Pythons

Packages (replaces pip)

Command What it does
uv pip install pandas Install into the active environment
uv pip install -r requirements.txt Install from a requirements file
uv pip compile requirements.in Generate pinned requirements.txt
uv pip freeze List installed with exact versions

uv pip ... mirrors pip syntax — drop-in replacement inside existing workflows.

Command What it does
uv init New project with pyproject.toml
uv add pandas Add dependency + update lockfile
uv add --dev pytest Dev-only dependency
uv remove pandas Remove dependency
uv sync Install everything to match the lockfile
uv run script.py Run with the project environment
uv lock (Re)generate uv.lock

Tools (replaces pipx)

Command What it does
uv tool install ruff Install a CLI tool in isolation
uv tool run jupyter lab Run a tool without installing it
uvx black file.py Shorthand for uv tool run

Common Operations

Quick data science environment

uv init myproject && cd myproject
uv add pandas numpy scikit-learn matplotlib jupyter
uv run jupyter lab

Reproduce a project exactly

git clone https://github.com/user/project && cd project
uv sync                  # creates .venv + installs locked versions
uv run python main.py

Migrate from pip + venv

uv venv && source .venv/bin/activate
uv pip install -r requirements.txt

Practical Examples

1. Zero-config project bootstrap

uv init ml-experiment
cd ml-experiment
uv add pandas scikit-learn torch --index https://download.pytorch.org/whl/cu121
uv add --dev pytest mypy ruff
uv run pytest

This creates pyproject.toml and uv.lock — environments anywhere become identical.

2. Throwaway script with dependencies

uv run --with pandas --with matplotlib python analyze.py

No project, no venv — uv builds an ephemeral environment.

3. Per-version Python experiments

uv python install 3.11 3.12
uv run --python 3.12 python -c "import sys; print(sys.version)"

Common Patterns

# Pin Python version for the project
echo "requires-python = \">=3.11,<3.13\"" >> pyproject.toml

# Tool without install
uvx black --check .

# Update all dependencies
uv lock --upgrade

Best Practices

  • Use uv add/uv sync for projects — the lockfile makes environments reproducible and fast.
  • Commit uv.lock — it's the single source of truth for exact versions.
  • Use uv python install instead of manually downloading interpreters.
  • Cache is shared and safe — uv cache clean only when you need disk space.
  • uv pip is for legacy/requirements workflows; prefer project mode for new work.
  • Works side-by-side with pip — no migration pressure on existing repos.

Common Mistakes

Mistake Consequence Correct approach
Mixing uv add and manual pip install in a project Lockfile out of sync uv add for everything, then uv sync
Editing pyproject.toml without uv lock Stale lockfile uv lock or use uv add
Ignoring the lockfile in git Non-reproducible installs Commit uv.lock
uv pip without an active venv Installs into system Python uv venv first (or use project mode)
Not pinning the Python version Env drifts across machines Set requires-python in pyproject.toml

Troubleshooting

Symptom Cause Fix
No Python 3.x found Managed interpreter missing uv python install 3.x
error: Failed to download Network/proxy Set UV_INDEX_URL / proxy env vars; retry
uv.lock out of date warning Deps changed outside uv uv lock then uv sync
Slow first run Downloading Python + packages Normal — subsequent runs hit the cache
Conflicts between uv pip and project mode Mixed workflows Pick project mode (uv add/uv sync)

Official Documentation

Last Updated

2026-09-06 — Initial version.