/uv

name: uv
description:
  Guide for using uv, the Python package and project manager. Use this when
  working with Python projects, scripts, packages, or tools.

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.