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.