uv: Python Package and Project Manager

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, formatting code, building packages, and publishing to package indexes.

When to use uv

Use uv when you want a single tool for managing Python versions, virtual environments, dependencies, and package publishing instead of combining pip, pyenv, pipx, and others. It is a strong default for new Python projects and for developers who value fast installs and reproducible lockfiles. If your project relies on non-Python scientific libraries, conda may be a better fit; for a comparison with pip, see What’s the difference between pip and uv?.

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

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

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

See How to install uv for alternative methods and troubleshooting.

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

# Remove a dependency
uv remove requests

# Read or update the project version
uv version
uv version 1.2.0
uv version --bump minor

# Resolve and lock dependencies
uv lock

# Install project and dependencies
uv sync

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

# Display the dependency tree
uv tree

# Export lockfile to requirements.txt format
uv export --format requirements-txt

# 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

Formatting

uv includes a built-in code formatting command powered by Ruff’s formatter:

# Format all Python files in the project
uv format

# Check formatting without making changes
uv format --check

# Show what would change
uv format --diff

Formatting configuration is read from the project’s pyproject.toml under [tool.ruff.format], the same settings Ruff uses directly.

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

Python Version Management

Install and manage Python interpreters without relying on system packages or pyenv.

# List available and installed Python versions
uv python list

# Install a specific Python version
uv python install 3.12

# Pin the project to a Python version
uv python pin 3.12

# Find where a Python version is installed
uv python find 3.12

See How to install Python with uv and How to change the Python version of a uv project for more detail.

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

Handbook guides

• Create your first Python project
• Setting up testing with pytest and uv
• Run your first Python script with uv
• How to install uv
• How to migrate from requirements.txt to pyproject.toml with uv
• How to change the Python version of a uv project
• uv: A Complete Guide
• What’s the difference between pip and uv?

Official documentation

• uv documentation
• Project management
• Python version management
• Tool management