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:

bash

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

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

Projects

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

Key commands:

bash

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

uv init                   # Create new projectuv add requests           # Add dependencyuv remove requests        # Remove dependencyuv sync                   # Install from lockfileuv run <command>          # Run commands in environmentuv run python -c ""       # Run Python in project environmentuv 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:

bash

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

uvx <tool> <args>            # Run a tool without installationuvx <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:

bash

uv venvuv pip install -r requirements.txtuv pip compile requirements.in -o requirements.txtuv pip sync requirements.txt
# Platform independent resolutionuv pip compile --universal requirements.in -o requirements.txt

uv venvuv pip install -r requirements.txtuv pip compile requirements.in -o requirements.txtuv pip sync requirements.txt
# Platform independent resolutionuv 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

bash

pyenv install 3.12       → uv python install 3.12pyenv versions           → uv python list --only-installedpyenv local 3.12         → uv python pin 3.12pyenv global 3.12        → uv python install 3.12 --default

pyenv install 3.12       → uv python install 3.12pyenv versions           → uv python list --only-installedpyenv local 3.12         → uv python pin 3.12pyenv global 3.12        → uv python install 3.12 --default

pipx → uvx

bash

pipx run ruff            → uvx ruffpipx install ruff        → uv tool install ruffpipx upgrade ruff        → uv tool upgrade ruffpipx list                → uv tool list

pipx run ruff            → uvx ruffpipx install ruff        → uv tool install ruffpipx upgrade ruff        → uv tool upgrade ruffpipx list                → uv tool list

pip and pip-tools → uv pip

bash

pip install package      → uv pip install packagepip install -r req.txt   → uv pip install -r req.txtpip freeze               → uv pip freezepip-compile req.in       → uv pip compile req.inpip-sync req.txt         → uv pip sync req.txtvirtualenv .venv         → uv venv

pip install package      → uv pip install packagepip install -r req.txt   → uv pip install -r req.txtpip freeze               → uv pip freezepip-compile req.in       → uv pip compile req.inpip-sync req.txt         → uv pip sync req.txtvirtualenv .venv         → uv venv

Uv

uv

When to use uv

Choosing the right workflow

Scripts

Projects

Tools

Pip interface

Migrating from other tools

pyenv → uv python

pipx → uvx

pip and pip-tools → uv pip

Common patterns

Don't use pip in uv projects

Don't run python directly

Don't manually manage environments in uv projects

Documentation

Source and attribution

More from astral-sh/claude-code-plugins

Ty

Ruff