UV Workflow Guidelines

Core Principles

1. Prefer uv run: Do not manually activate virtual environments. Use uv run <command> to execute scripts in the project context.
2. Lockfile Integrity: Always run uv sync if uv.lock changes. Never manually edit uv.lock.
3. Reproducibility: Ensure python-version is pinned in pyproject.toml via uv python pin.

Common Operations

Dependency Management

• Add Package: uv add <package> (Use --dev for development tools like pytest/ruff)
• Remove Package: uv remove <package>
• Update All: uv lock --upgrade

Environment

• Sync/Install: uv sync (Run this immediately if pyproject.toml is pulled from git)
• Reset: If environment is corrupted, delete .venv and run uv sync.

Execution

• Run Script: uv run script.py
• Run Tool: uv run pytest

Advanced Reference

For complex resolution behavior or workspace configuration, see REFERENCES.md.