uv

Overview

uv is a modern Python package and project manager from Astral, written in Rust and designed to be 10–100x faster than pip. It provides a unified interface for managing Python versions, virtual environments, project dependencies, lockfiles, and standalone tools — replacing pip, pip-tools, pipx, poetry, pyenv, and virtualenv in one binary.

Installation

Linux / macOS (recommended)

curl -LsSf https://astral.sh/uv/install.sh | sh
# Or via pip
pip install uv

Windows (PowerShell)

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

Homebrew (macOS / Linux)

brew install uv

Verify installation

uv --version
uv self update   # Update uv itself

Configuration

Environment variables

UV_PYTHON=3.12          # Default Python version
UV_CACHE_DIR=~/.cache/uv  # Custom cache location
UV_NO_CACHE=1           # Disable caching
UV_INDEX_URL=https://pypi.org/simple  # Custom index
UV_EXTRA_INDEX_URL=https://my.pypi.org/simple  # Additional index
UV_SYSTEM_PYTHON=1      # Allow using system Python
UV_LINK_MODE=copy       # hardlink | symlink | copy | clone

`uv.toml` (project-level config)

[tool.uv]
python = "3.12"
index-url = "https://pypi.org/simple"

[[tool.uv.index]]
name = "internal"
url = "https://internal.company.com/simple"

`pyproject.toml` integration

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.110",
    "httpx>=0.27",
]

[project.optional-dependencies]
dev = ["pytest", "ruff"]

[tool.uv]
dev-dependencies = ["pytest>=8", "ruff>=0.4"]

Core Commands

Command	Description
`uv init my-project`	Create a new project with pyproject.toml
`uv add requests`	Add a dependency and update lockfile
`uv add --dev pytest`	Add a dev dependency
`uv remove requests`	Remove a dependency
`uv sync`	Install all dependencies from lockfile
`uv lock`	Generate/update uv.lock without installing
`uv run python script.py`	Run script in project virtual environment
`uv run pytest`	Run a command in the project environment
`uv pip install requests`	pip-compatible install
`uv pip compile requirements.in`	Compile requirements like pip-tools
`uv pip sync requirements.txt`	Sync environment to requirements file
`uv venv`	Create a virtual environment
`uv python install 3.12`	Download and install Python 3.12
`uv python list`	List available Python versions
`uv python pin 3.11`	Pin project to Python version
`uv tool install ruff`	Install a CLI tool globally
`uv tool run ruff check .`	Run a tool without installing
`uvx ruff check .`	Shorthand for uv tool run
`uv tree`	Show dependency tree
`uv export`	Export dependencies to requirements.txt

Advanced Usage

Python version management

# Install specific Python versions
uv python install 3.11 3.12 3.13

# List installed and available versions
uv python list

# Pin a project to a version (writes .python-version)
uv python pin 3.12

# Use a specific version for a command
uv run --python 3.11 python --version

# Find the Python interpreter uv would use
uv python find 3.12

Virtual environment control

# Create venv in default .venv/
uv venv

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

# Create venv in custom location
uv venv /path/to/myenv

# Activate (standard shell activation still works)
source .venv/bin/activate

# Or just use uv run to avoid activating
uv run python -c "import sys; print(sys.version)"

Lockfile and reproducible builds

# Generate lockfile without installing
uv lock

# Install exactly what's in the lockfile
uv sync --frozen

# Check lockfile is up-to-date (CI use)
uv lock --check

# Export to pip-compatible requirements
uv export --format requirements-txt > requirements.txt
uv export --no-hashes > requirements.txt
uv export --only-dev > dev-requirements.txt

Workspace (monorepo) support

# Root pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

# Sync entire workspace
uv sync --all-packages

# Sync a specific member
uv sync --package my-lib

Dependency groups and extras

# Add with extras
uv add "fastapi[standard]"

# Sync with optional extras
uv sync --extra all

# Add to a named group
uv add --group lint ruff mypy

# Sync only specific groups
uv sync --group dev --group lint

Tool management (replaces pipx)

# Install tool globally
uv tool install ruff
uv tool install black
uv tool install httpie

# List installed tools
uv tool list

# Run a tool without permanent install
uvx cowsay "hello"

# Upgrade a tool
uv tool upgrade ruff

# Uninstall a tool
uv tool uninstall ruff

# Install specific version of a tool
uv tool install ruff==0.4.0

Advanced pip interface

Command	Description
`uv pip install -r requirements.txt`	Install from requirements file
`uv pip install -e .`	Editable install
`uv pip install --index-url URL pkg`	Install from custom index
`uv pip list`	List installed packages
`uv pip show requests`	Show package details
`uv pip freeze`	Output installed packages
`uv pip check`	Check for dependency conflicts
`uv pip uninstall requests`	Uninstall a package
`uv pip compile pyproject.toml -o requirements.txt`	Compile dependencies
`uv pip sync requirements.txt`	Sync environment exactly

Common Workflows

Starting a new project

# Initialize project
uv init my-api
cd my-api

# Add dependencies
uv add fastapi uvicorn httpx
uv add --dev pytest pytest-asyncio ruff

# Run the application
uv run uvicorn main:app --reload

# Run tests
uv run pytest

Migrating from pip / requirements.txt

# Convert requirements.txt to pyproject.toml-managed project
uv init --no-readme
uv add $(cat requirements.txt | grep -v '^#' | tr '\n' ' ')

# Or keep using requirements.txt with uv's pip interface
uv pip install -r requirements.txt

Migrating from poetry

# uv reads pyproject.toml natively
# Just replace `poetry install` with:
uv sync

# Replace `poetry add X` with:
uv add X

# Replace `poetry run X` with:
uv run X

CI/CD (GitHub Actions)

- uses: astral-sh/setup-uv@v5
  with:
    version: "latest"
    enable-cache: true

- name: Install dependencies
  run: uv sync --frozen

- name: Run tests
  run: uv run pytest

Docker usage

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

COPY . .
CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0"]

Scripting with inline dependencies

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = ["httpx", "rich"]
# ///

import httpx
from rich import print

data = httpx.get("https://api.github.com").json()
print(data)

uv run my_script.py  # uv installs deps automatically
chmod +x my_script.py && ./my_script.py

Tips and Best Practices

Commit the lockfile. Always commit uv.lock to version control for reproducible installs across your team and CI.

Use uv sync --frozen in CI. This fails if the lockfile is out of date, preventing accidental dependency drift in production.

Prefer uv run over activating the venv. Running uv run pytest instead of activating .venv is more portable and works in scripts without shell magic.

Cache in CI. Use astral-sh/setup-uv with enable-cache: true for fast GitHub Actions runs. uv caches downloaded wheels and metadata aggressively.

Use uvx for one-off tools. Instead of globally installing linters or generators just to run them once, use uvx ruff check . — it downloads, caches, and runs without polluting your environment.

Separate dev dependencies from production. Use uv add --dev or --group to keep production images lean. Then uv sync --no-dev in Docker.

Pin Python version in .python-version. Run uv python pin 3.12 to create this file so all teammates and CI use the same interpreter without extra config.

Use workspaces for monorepos. If you have multiple related packages, uv workspaces let you share a single lockfile and avoid duplicating dependencies.

Check for outdated packages. Use uv tree --outdated to see which dependencies have newer versions available before running uv lock --upgrade.

Speed comparison. uv is typically 10–100x faster than pip for cold installs and near-instant for cached installs. The Rust implementation eliminates Python overhead in the resolver.

uv