uv

name	uv
description	Prioritize uv over pip for all Python package management and execution. When running ANY Python command or CLI tool (python, dbt, pytest, etc.), MUST wrap with uv run

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 <tool>	Ferramenta do projeto- precisa importar seus módulos, usada regularmente	uv run pytest tests/
uvx <tool>	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 <package>	uv add <package>
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 <package>	uv add <package>
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 <command>	-
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 <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