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. Only 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 Important: Don't use the pip interface unless clearly needed. Don't introduce new requirements.txt files. Prefer uv init for new projects. Migrating from other tools pyenv → uv python pyenv install 3.12 → uv python install 3.12 pyenv versions → uv python list --only-installed pyenv local 3.12 → uv python pin 3.12 pyenv global 3.12 → uv python install 3.12 --default pipx → uvx pipx run ruff → uvx ruff pipx install ruff → uv tool install ruff pipx upgrade ruff → uv tool upgrade ruff pipx list → uv tool list pip and pip-tools → uv pip pip install package → uv pip install package pip install -r req.txt → uv pip install -r req.txt pip freeze → uv pip freeze pip-compile req.in → uv pip compile req.in pip-sync req.txt → uv pip sync req.txt virtualenv .venv → uv venv Common patterns Don't use pip in uv projects

Bad

pip install requests

Good

uv add requests Don't run python directly

Bad

python script.py

Good

uv run script.py

Bad

python -c "..."

Good

uv run python -c "..."

Bad

python3.12 -c "..."

Good

uvx python@3.12 -c "..." Don't manually manage environments in uv projects

Bad

python -m venv .venv source .venv/bin/activate

Good

uv run < command

Documentation For detailed information, read the official documentation: https://docs.astral.sh/uv/llms.txt The documentation links to specific pages for each of these workflows.