UV Priority

CRITICAL: Always Wrap Python Commands with uv or uvx

This is a mandatory skill for all Python-related tasks. When the user mentions Python, dbt, or ANY Python package, you MUST:

1. NEVER run Python commands directly (python, python3, dbt, pytest, etc.)
2. ALWAYS wrap them with uv run or uvx
3. NEVER install packages with pip install
4. ALWAYS use uv add or uv pip install

uv run vs uvx: When to Use Each

Quick Decision Guide

Preciso rodar uma ferramenta Python?
├─ A ferramenta precisa importar meus módulos do projeto?
│  └─ SIM → uv run <comando>
└─ A ferramenta só analisa/transforma código externo?
   └─ SIM → uvx <comando>

Use uvx for External Tools

uvx creates a temporary, isolated environment. Use it for tools that:

• Analyze code without importing project modules (linters, formatters, type checkers)
• Are one-off utilities not tied to your project
• Shouldn't pollute your project's dependencies

uvx ruff check .          # Linter - analisa sintaxe, não importa seus módulos
uvx black .               # Formatter - manipula texto, não importa seus módulos
uvx mypy .                # Type checker - analisa tipos, não precisa rodar seu código
uvx isort .               # Organizador de imports - só lê arquivos
uvx ruff@latest check .   # Use specific version

Use uv run for Project Tools

uv run uses your project's existing virtual environment. Use it for tools that:

• Need to import your project modules
• Are part of your development workflow with project dependencies
• Run tests or your application

uv run pytest tests/      # Test runner - precisa importar seus módulos
uv run python main.py     # Sua aplicação
uv run python -m myapp.cli  # CLI do seu app
uv run dbt run            # dbt com suas transformações do projeto

Rule of Consistency

If the project already uses uv run for a specific tool, continue using it.

• If you see uv run ruff check . in the project, don't change to uvx
• If the user specified uv run pytest, maintain the pattern
• Project consistency takes precedence over the "ideal rule"

Why? Changing from uv run to uvx (or vice-versa) mid-project can:

• Break scripts/CI that expect the specific command
• Confuse other developers
• Create unnecessary inconsistency

Command Translation Rules

When to Use

Use when:

• Installing ANY Python package or dependency (for ANY Python app: web apps, scripts, data processing, dbt, ML, etc.)
• Setting up Python projects (web apps like Flask/Django/FastAPI, data science, ML, automation, dbt, etc.)
• Installing dependencies for ANY Python-based application
• Creating virtual environments
• Running Python scripts
• Running tests (pytest, unittest, etc.)
• Using dbt commands (dbt-core, dbt-snowflake, etc.)
• ANY task involving Python packages or dependencies

Command Substitutions (MANDATORY)

NEVER use these pip commands. ALWAYS use the uv equivalent:

Popular Python Tools with CLI

These are commonly installed Python packages that have CLI commands. When installing or running them, always use uv:

Note: For linters, formatters, and type checkers, uvx is preferred (doesn't pollute project dependencies). For tools that need to import your project modules (like pytest with your app code), use uv run.

Running Any Python Package CLI

For ANY Python package with a CLI command:

# Option 1: Run as external tool (preferred for linters, formatters, one-off tools)
uvx <cli-command>

# Option 2: Install and run within project environment
uv add <package>
uv run <cli-command>

# Option 3: Run with specific version
uvx <package>@version <cli-command>

Environment and Scripts

Priority

uv (with uv run or uvx) is the ONLY option for Python package management and execution.

Execution priority:

1. uv run <command> - for tools that need project dependencies
2. uvx <command> - for external tools that don't need project modules

Only consider pip as a fallback if:

1. The user explicitly requests pip
2. uv is not available on the system
3. You receive explicit confirmation from the user