---

name: basic_uv description: Use when running or explaining uv or ty commands, managing dependencies/lockfiles/virtualenvs, or running Python in this repo.

Basic uv / ty

Overview

Use uv as the project package manager and runner; use ty for type checks. Provide command-first guidance and state what each command changes (pyproject.toml, uv.lock, or the virtual environment).

Workflow

• Detect uv project state by checking for pyproject.toml and uv.lock.
• Sync before running tools when accuracy matters: uv sync.
• Run tools through uv to ensure the project environment is used: uv run <cmd>.
• Prefer uv run python <script_or_module> over plain python when coding or executing Python in this repo.
• Call out side effects explicitly: uv add/remove update pyproject.toml and uv.lock; uv sync changes the environment.

Common uv Commands

• Initialize a project: uv init
• Add deps: uv add <pkg>; dev deps: uv add --dev <pkg>; group deps: uv add --group <group> <pkg>
• Remove deps: uv remove <pkg>
• Lock deps: uv lock (update uv.lock); uv lock --check (CI check); uv lock --upgrade (allow upgrades)
• Sync env: uv sync; uv sync --frozen (do not update uv.lock); uv sync --group <group> (include group)
• Run commands: uv run <cmd>; uv run --no-sync <cmd> (skip sync); uv run --group <group> <cmd>
• Inspect deps: uv tree
• Export lockfile: uv export
• Manage Python installs: uv python list|install|find|pin
• Tool runner: uv tool run <pkg> <cmd>; install: uv tool install <pkg>
• pip-compat mode: uv pip install|compile|sync|list|freeze|check

Common ty Commands

• Type check: uv run ty check [PATHS]
• Watch mode: uv run ty check --watch
• Config override: uv run ty check --config KEY=VALUE
• Config file: uv run ty check --config-file path/to/ty.toml
• Exclude paths: uv run ty check --exclude 'pattern'
• Target Python: uv run ty check --python-version 3.12
• Specify env: uv run ty check --python path/to/python
• LSP server: uv run ty server
• Shell completion: ty generate-shell-completion <SHELL>

Project Reference

• If the repo provides a local cheat sheet, consult it for project-specific conventions: docs/ty-uv-commands.md.