Tool Uv

tool-uv

When To Use

• Manage Python environments and dependencies quickly.
• Run project commands in the correct managed environment.
• Bootstrap, lint, test, and typecheck Python workflows.

Trusted Commands

uv venv
uv pip install requests
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv run --with requests script.py
uv init my-project
uv add requests
uv sync
uv run pytest tests/
uv run pyright .

Safe Defaults

• Use uv run for project commands to avoid environment drift.
• Keep dependency and lockfile changes explicit and reviewed.
• Confirm with user before adding/upgrading dependencies.

Common Pitfalls

• Running tools outside uv can select the wrong interpreter.
• Assuming system Python version matches project constraints.
• Mixing ad-hoc pip workflows with managed uv project flows.

Output Interpretation

• uv sync reports dependency resolution and installation updates.
• uv run failures usually point to tool/code issues, not uv itself.
• uv pip commands remain broadly pip-compatible.

Why It Matters For Agents

• Dramatically reduces dependency setup time.
• Provides a consistent execution wrapper for deterministic automation.

Repo Conventions

• Python workflows in this repository are uv-managed.
• Run lint, type checks, and tests for behavior changes before completion.

Trigger Examples

• Should trigger: "Install deps and run the pytest suite."
• Should trigger: "Run ruff and pyright in the project environment."
• Should not trigger: "Open an interactive fuzzy selector in terminal."