uv: Python Package and Project Manager

uv is a fast Python package and project manager, built by Astral (now part of OpenAI), that replaces pip, pip-tools, pipx, Poetry, pyenv, and virtualenv with a single tool.

One uv binary installs Python interpreters, resolves and locks dependencies, creates virtual environmentsAn isolated folder where Python installs packages for one project, keeping them separate from other projects and your system Python. Learn more → , runs scripts and command-line tools, formats and type-checks code, and builds and publishes packages. It is written in Rust and open source under the MIT and Apache-2.0 licenses.

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

powershell -ExecutionPolicy ByPass -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 my-project
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.

Workspace Inspection

uv workspace inspects a multi-package workspace: its members, their paths on disk, and its resolved metadata.

# List the members of the workspace
uv workspace list

# Print workspace metadata as JSON
uv workspace metadata

# Print the path of one workspace member
uv workspace dir --package my-library

See How to set up a Python monorepo with uv workspaces for the [tool.uv.workspace] layout these commands read.

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.

Type Checking

uv check type-checks the project’s Python code using ty. By default, all Python files in the project are checked after syncing the virtual environment with the project’s dependencies.

# Type check the current project
uv check

# Pin ty to a specific version
uv check --ty-version 0.0.75

# Type check with a specific dependency group installed
uv check --group typechecking

# Skip syncing the virtual environment before checking
uv check --no-sync

For CI integration, see How to use ty in CI.

Security Auditing

uv audit 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. For why a uv-managed interpreter is a safer base than a Homebrew one, see Should I use Homebrew to install Python?.

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

# Inspect an installed environment (works without a pyproject.toml)
uv pip tree --python .venv/bin/python
uv pip tree --invert --package markupsafe --show-version-specifiers
uv pip check

Unlike uv tree, which reads a project’s lockfile, the uv pip tree command reads installed packages and accepts any interpreter through --python. See How to inspect a virtual environment you did not create.

Index Authentication

uv auth stores and retrieves credentials for private package indexes, so a token stays out of pyproject.toml and out of shell history.

# Store credentials for an index
uv auth login https://example.com/simple --username alice --token "$TOKEN"

# Print the stored token for an index
uv auth token https://example.com/simple

# Remove stored credentials
uv auth logout https://example.com/simple

# Show where uv keeps its credentials
uv auth dir

See How to use private package indexes with uv for wiring an authenticated index into a project.

Cons

• Still pre-1.0: uv is on the 0.x version line, and minor releases have changed behavior, so pin the uv version in CI rather than tracking the latest release.
• Single-vendor governance: uv is developed by Astral (now part of OpenAI), so its roadmap and eventual commercial model rest with one company rather than a community foundation.
• No plugin system: unlike Poetry, uv exposes no third-party plugin interface, so a workflow it does not cover natively falls back to a separate tool.