UV

UV is a fast Python package manager. Two modes:

Scripts vs Projects

Use scripts when:

• Single .py file

• Quick utility, one-off task

• No shared dependencies across files

Use projects when:

• Multiple files, modules, or packages

• Team collaboration

• Need reproducible environments

• Building a library or application

Scripts

Standalone Python files with inline dependencies (PEP 723).

#!/usr/bin/env -S uv run --script

/// script

requires-python = ">=3.12"

dependencies = ["requests", "rich"]

///

import requests from rich import print

Run: uv run script.py

See references/scripts.md for full guide.

Projects

Structured Python with pyproject.toml and lockfile.

uv init myproject cd myproject uv add requests uv run python main.py

Key files:

• pyproject.toml

• metadata and dependencies

• uv.lock

• exact versions for reproducibility

• .python-version

• Python version

See references/projects.md for full guide.

Common Patterns

uv run pytest # Run in project env uv add --dev pytest # Dev dependency uvx ruff check . # One-off tool execution uv run --with rich script.py # Script with ad-hoc dep