uv

uv is a high-performance Python package and project manager that provides a unified interface for installing Python versions, managing dependencies, creating virtual environments, running scripts, building packages, and publishing to package indexes.

Note

This is a reference guide for uv. For a tutorial on how to use uv, see Create your first Python project.

Why uv?

Traditional Python development involves juggling multiple tools (e.g. pip, pip-tools, pipx, poetry, pyenv, virtualenv), each with different interfaces and behaviors. uv unifies these workflows while delivering 10-100x performance improvements over existing solutions.

  • Speed: 10-100x faster than traditional Python tools
  • Simplicity: One tool for all Python packaging needs
  • Standards: Full compatibility with modern Python packaging standards
  • Reliability: Reproducible builds with universal lockfiles

Installation

Quick Install

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

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

See the official installation guide for more methods.

Command Categories

Project Management

Projects use pyproject.toml for configuration and uv.lock for dependency locking.

# Initialize new project
uv init my-project

# Add dependencies
uv add requests
uv add --dev pytest  # development dependency

# Install project and dependencies
uv sync

# Run commands in project environment
uv run python main.py
uv run pytest

# Build distributions
uv build

# Publish to PyPI
uv publish

Script Execution

Run standalone Python scripts with automatic dependency management.

# Run script with inline dependencies
uv run script.py

# Run with additional dependencies
uv run --with requests script.py

# Add dependencies to script metadata
uv add --script script.py requests

Inline Script Dependencies

uv allows you to specify dependencies for a script in the script itself, using the dependencies key.

Run uv add --script script.py requests rich to add the requests and rich dependencies to your script.

# /// script
# dependencies = ["requests", "rich"]
# requires-python = ">=3.8"
# ///

import requests
from rich import print

Note

Inline script dependencies are a PEP 723 compliant way to specify dependencies for a script.

Tool Management

Install and run Python-based CLI tools in isolated environments.

# Run tool temporarily
uvx ruff .

# Install tool globally
uv tool install ruff

# Upgrade tools
uv tool upgrade ruff
uv tool upgrade --all

pip-Compatible Interface

uv provides a drop-in replacement for pip/pip-tools workflows with enhanced performance.

# Create virtual environment
uv venv

# Install packages
uv pip install requests
uv pip install -r requirements.txt
uv pip install -e .  # editable install

# Generate lockfiles
uv pip compile requirements.in
uv pip compile --universal requirements.in  # cross-platform

# Sync environment with lockfile
uv pip sync requirements.txt

Learn More

Last updated on

Please submit corrections and feedback...