Astral Uv

uv: Python Package and Project Manager

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

Navigation Rule

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

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

Exclusion Rule

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

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

Workflow Selection Rule

Choose the right workflow based on your use case:

Scripts Workflow

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

See references/script-execution.md for script execution examples.

Projects Workflow

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

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

See references/project-setup.md for project setup examples.

Tools Workflow

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

Security Rule: uvx runs tools from PyPI by package name. This can be unsafe - only run well-known tools. Only use uv tool install when specifically requested by the user.

Pip Interface Workflow

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

Best Practice Rule: Don't use the pip interface unless clearly needed. Don't introduce new requirements.txt files. Prefer uv init for new projects.

Migration Rules

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

See references/migration.md for migration examples.

Common Pattern Rules

Don't Use pip in uv Projects Rule

# Bad
pip install requests

# Good
uv add requests

Don't Run python Directly Rule

# 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 Rule

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

# Good
uv run <command>

Documentation Reference

For detailed information, see the official documentation at https://docs.astral.sh/uv/llms.txt

Additional References

• Lockfile management: See references/lockfiles.md
• Python version management: See references/python-versions.md
• Common workflows: See references/workflows.md