Skip to content

uv: Python Package and Project Manager

by Tim Hopper
uv Packaging

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.

Tip

This page is a command reference for users who already know uv. For a guide that explains what uv is, covers installation, core workflows, benchmarks, and migration from pip and Poetry, see uv: A Complete Guide. For a hands-on first project, see Create your first Python project.

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. For background on how the ecosystem ended up so fragmented, see Why are there so many Python packaging tools?.

  • 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

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

See How to run tests using uv for configuring pytest with uv run, and Understanding dependency groups in uv for how [dependency-groups] interacts with uv sync --group.

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.

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. To make a uv-managed interpreter available as python outside a uv project, see How to add Python to your system path with uv.

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

Official documentation

This handbook is free, independent, and ad-free. If it saved you time, consider sponsoring it on GitHub.

Last updated on
tyuvx

Please submit corrections and feedback...