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

| Command | When to Use | Example |

|---------|-------------|---------|

| uv run | Ferramenta do projeto - precisa importar seus módulos, usada regularmente | uv run pytest tests/ |

| uvx | Utilitário externo - usa Python como runtime, mas não é parte do seu app | uvx ruff check . |

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

| NEVER run this | ALWAYS run this instead |

|----------------|------------------------|

| python script.py | uv run python script.py |

| python -c "import..." | uv run python -c "import..." |

| python -m module | uv run python -m module |

| python3 script.py | uv run python3 script.py |

| dbt --version | uv run dbt --version |

| dbt run | uv run dbt run |

| dbt debug | uv run dbt debug |

| dbt deps | uv run dbt deps |

| pytest | uv run pytest (imports project modules) or uvx pytest (one-off) |

| pytest tests/ | uv run pytest tests/ (imports project modules) or uvx pytest tests/ (one-off) |

| black . | uvx black . (preferred - external tool) or uv run black . (if already in project) |

| ruff check . | uvx ruff check . (preferred - external tool) or uv run ruff check . (if already in project) |

| mypy . | uvx mypy . (preferred - external tool) or uv run mypy . (if already in project) |

| pip install | uv add |

| pip install -r requirements.txt | uv pip install -r requirements.txt |

| pip list | uv pip list |

| pip freeze | uv pip freeze |

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:

| NEVER use pip | ALWAYS use uv |

|---------------|---------------|

| pip install | uv add |

| pip install -r requirements.txt | uv pip install -r requirements.txt |

| pip list | uv pip list |

| pip freeze | uv pip freeze |

Popular Python Tools with CLI

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

| Tool | Install with uv | Run with uv (project) | Run with uvx (external) |

|------|----------------|------------------------|--------------------------|

| dbt (dbt-core) | uv add dbt-snowflake (or dbt-postgres) | uv run dbt | - |

| pytest | uv add pytest | uv run pytest (imports project modules) | uvx pytest (one-off) |

| black (formatter) | uv add black | uv run black (if in project) | uvx black . (preferred) |

| ruff (linter) | uv add ruff | uv run ruff (if in project) | uvx ruff check . (preferred) |

| mypy (type checker) | uv add mypy | uv run mypy (if in project) | uvx mypy . (preferred) |

| flake8 (linter) | uv add flake8 | uv run flake8 | uvx flake8 |

| pylint (linter) | uv add pylint | uv run pylint | uvx pylint |

| isort (import sorter) | uv add isort | uv run isort | uvx isort . |

| poetry (dependency manager) | uv add poetry | uv run poetry | uvx poetry |

| pipenv (dependency manager) | uv add pipenv | uv run pipenv | uvx pipenv |

| cookiecutter (project templates) | uv add cookiecutter | uv run cookiecutter | uvx cookiecutter |

| httpie (HTTP client) | uv add httpie | uv run http | uvx http |

| mycli (MySQL CLI) | uv add mycli | uv run mycli | uvx mycli |

| pgcli (PostgreSQL CLI) | uv add pgcli | uv run pgcli | uvx pgcli |

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

| NEVER use pip | ALWAYS use uv |

|---------------|---------------|

| python -m venv .venv | uv venv |

| python script.py | uv run script.py |

| python -m module | uv run python -m module |

| python -m pip install | uv add |

| python -m pip list | uv pip list |

Priority

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

Execution priority:

1. uv run - for tools that need project dependencies
2. uvx - 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