| name | tool-uv |
| description | Use uv for fast Python dependency sync, environment management, and command execution. Trigger for Python setup, install, lint, test, and script workflows in this repo. |
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."
