uv

uv is a next-generation Python package and project manager from Astral, written in Rust, aiming to replace pip, pip-tools, venv, pipx, poetry, pyenv, and other scattered tools with a single one. Its dependency resolution and installation are one to two orders of magnitude faster than traditional tools, and it ships with its own Python version management — making it the community’s recommended default starting point today.

Installation

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

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

# Or install via pipx
pipx install uv

Python Version Management

uv has built-in downloading and management of Python interpreters — no need to install pyenv separately:

# Install specific Python versions (downloaded automatically)
uv python install 3.12 3.13

# List installed / installable versions
uv python list
uv python list --only-installed

# Pin a Python version for the current directory, generating a .python-version file
uv python pin 3.12

Quick Virtual Environments (pip-Compatible Mode)

If you just want a lightweight virtual environment similar to venv, uv venv is a much faster drop-in replacement for python -m venv:

# Create a virtual environment, optionally pinning a Python version (downloaded automatically if missing)
uv venv --python 3.12.0

# Activation works exactly like venv
source .venv/bin/activate

# Use uv to accelerate pip installs (pip-compatible CLI)
uv pip install requests
uv pip install -r requirements.txt

Project Mode (Recommended): pyproject.toml + Lockfile

For real projects, uv’s project-management mode is the recommended path: declare dependencies in pyproject.toml and lock exact versions in uv.lock, guaranteeing that your team and CI install the exact same dependency tree every time:

# Initialize a new project, generating a standard pyproject.toml structure
uv init example
cd example

# Add a dependency: updates pyproject.toml, resolves and writes uv.lock, installs into .venv
uv add ruff

# Add a dev-only dependency (written to dependency-groups.dev)
uv add --dev pytest

# Remove a dependency
uv remove ruff

# Run a command inside the project's virtual environment, no manual activate needed
uv run pytest

# Re-resolve pyproject.toml and regenerate the lockfile
uv lock

# Sync .venv to exactly match the lockfile
uv sync

# View the dependency tree
uv tree

uv.lock pins the exact versions and hashes of every dependency, including transitive ones — giving you genuinely reproducible builds, unlike requirements.txt. This is the biggest difference between uv’s project mode and venv+pip.

Running Scripts Directly (Inline Dependency Declarations)

For single-file scripts, uv supports declaring dependencies in a comment header at the top of the file; uv run automatically creates a temporary environment, installs the dependencies, and runs the script:

uv add --script example.py requests

# example.py
# /// script
# dependencies = ["requests"]
# ///
import requests
print(requests.get("https://astral.sh").status_code)

uv run example.py   # Automatically resolves dependencies and runs — no manual environment setup

uv replaces poetry add with uv add/uv remove, replaces pyenv with uv python install/pin, and replaces pipx run with uv run --with — a single tool now covers work that used to require five or six separate tools in the Python ecosystem, which is why it’s the default recommendation for new projects today.

Last updated on 2026-08-07

conda pyenv