uv

uv

uv is an extremely fast Python package and project manager. It replaces pip, pip-tools, pipx, pyenv, virtualenv, poetry, etc.

When to use uv

Always use uv for Python work, especially if you see:

• The uv.lock file
• uv headers in requirements* files, e.g., "This file was autogenerated by uv"

Don't use uv in projects managed by other tools:

• Poetry projects (identifiable by poetry.lock file)
• PDM projects (identifiable by pdm.lock file)

Choosing the right workflow

Scripts

Use when: Running single Python files and standalone scripts.

Key commands:

uv run script.py                      # Run a script
uv run --with requests script.py      # Run with additional packages
uv add --script script.py requests    # Add dependencies inline to the script

Projects

Use when: There is a pyproject.toml or uv.lock

Key commands:

uv init                   # Create new project
uv add requests           # Add dependency
uv remove requests        # Remove dependency
uv sync                   # Install from lockfile
uv run <command>          # Run commands in environment
uv run python -c ""       # Run Python in project environment
uv run -p 3.12 <command>  # Run with specific Python version

Tools

Use when: Running command-line tools (e.g., ruff, ty, pytest) without installation.

Key commands:

uvx <tool> <args>            # Run a tool without installation
uvx <tool>@<version> <args>  # Run a specific version of a tool

Important:

• uvx runs tools from PyPI by package name. This can be unsafe - only run well-known tools.
• Use uv tool install only when specifically requested by the user.

Pip interface

Use when: Legacy workflows with requirements.txt or manual environment management, no uv.lock present.

Key commands:

uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

# Platform independent resolution
uv pip compile --universal requirements.in -o requirements.txt