Skip to content

uv: Python Package and Project Manager

by Tim Hopper · Markdown
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](https://pydevtools.com/handbook/reference/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.

Note

uv format is experimental and prints a preview warning. Its interface may change in future uv releases. For a stable formatting setup today, run Ruff directly with uvx ruff format.

Security Auditing

uv audit (added in uv 0.10.12) checks the project’s locked dependencies against the OSV (Open Source Vulnerabilities) database and exits with a non-zero status when any are found.

# Audit the project's locked dependencies
uv audit

# Audit a single PEP 723 script
uv audit --script analysis.py

# Audit a specific dependency group
uv audit --only-group dev

# Ignore a vulnerability by advisory ID
uv audit --ignore GHSA-xxxx-xxxx-xxxx

# Ignore until an upstream fix is published
uv audit --ignore-until-fixed GHSA-xxxx-xxxx-xxxx

For a CI walkthrough and a comparison with pip-audit, see How to scan Python dependencies for vulnerabilities.

Tool Management

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

# Run tool temporarily
uvx ruff check .

# 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