Gerenciador de Pacotes UV

Guia completo para usar o uv, um instalador e resolvedor de pacotes Python extremamente rápido escrito em Rust, para gerenciamento moderno de projetos Python e fluxos de trabalho de dependência.

Quando Usar Esta Habilidade

• Configurar novos projetos Python rapidamente
• Gerenciar dependências Python mais rápido que o pip
• Criar e gerenciar ambientes virtuais
• Instalar interpretadores Python
• Resolver conflitos de dependência eficientemente
• Migrar de pip/pip-tools/poetry
• Acelerar pipelines de CI/CD
• Gerenciar projetos Python monorepo
• Trabalhar com lockfiles para compilações reproduzíveis
• Otimizar compilações Docker com dependências Python

Conceitos Principais

1. O que é uv?

• Instalador de pacotes ultrarrápido: 10-100x mais rápido que o pip
• Escrito em Rust: Aproveita o desempenho do Rust
• Substituto direto do pip: Compatível com fluxos de trabalho do pip
• Gerenciador de ambientes virtuais: Cria e gerencia venvs
• Instalador Python: Baixa e gerencia versões do Python
• Resolvedor: Resolução avançada de dependências
• Suporte a lockfile: Instalações reproduzíveis

2. Principais Recursos

• Velocidades de instalação incrivelmente rápidas
• Eficiente em espaço em disco com cache global
• Compatível com pip, pip-tools, poetry
• Resolução abrangente de dependências
• Suporte multiplataforma (Linux, macOS, Windows)
• Nenhum Python necessário para instalação
• Suporte integrado a ambientes virtuais

3. UV vs Ferramentas Tradicionais

• vs pip: 10-100x mais rápido, melhor resolvedor
• vs pip-tools: Mais rápido, mais simples, melhor UX
• vs poetry: Mais rápido, menos opinativo, mais leve
• vs conda: Mais rápido, focado em Python

Instalação

Instalação Rápida

# Using Homebrew (macOS or Linux)
brew install uv

# Using Cargo (if you have Rust)
cargo install --locked uv

No Windows, use o WinGet:

winget install --id=astral-sh.uv -e

Use o guia de instalação oficial para outros métodos de instalação suportados.

Verificar Instalação

uv --version
# uv 0.x.x

Início Rápido

Criar um Novo Projeto

# Create new project with virtual environment
uv init my-project
cd my-project

# Or create in current directory
uv init .

# Initialize creates:
# - .python-version (Python version)
# - pyproject.toml (project config)
# - README.md
# - .gitignore

Instalar Dependências

# Install packages (creates venv if needed)
uv add requests pandas

# Install dev dependencies
uv add --dev pytest black ruff

# Install from requirements.txt
uv pip install -r requirements.txt

# Install from pyproject.toml
uv sync

Gerenciamento de Ambientes Virtuais

Padrão 1: Criando Ambientes Virtuais

# Create virtual environment with uv
uv venv

# Create with specific Python version
uv venv --python 3.12

# Create with custom name
uv venv my-env

# Create with system site packages
uv venv --system-site-packages

# Specify location
uv venv /path/to/venv

Padrão 2: Ativando Ambientes Virtuais

# Linux/macOS
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Or use uv run (no activation needed)
uv run python script.py
uv run pytest

Padrão 3: Usando uv run

# Run Python script (auto-activates venv)
uv run python app.py

# Run installed CLI tool
uv run black .
uv run pytest

# Run with specific Python version
uv run --python 3.11 python script.py

# Pass arguments
uv run python script.py --arg value

Gerenciamento de Pacotes

Padrão 4: Adicionando Dependências

# Add package (adds to pyproject.toml)
uv add requests

# Add with version constraint
uv add "django>=4.0,<5.0"

# Add multiple packages
uv add numpy pandas matplotlib

# Add dev dependency
uv add --dev pytest pytest-cov

# Add optional dependency group
uv add --optional docs sphinx

# Add from git
uv add git+https://github.com/user/repo.git

# Add from git with specific ref
uv add git+https://github.com/user/repo.git@v1.0.0

# Add from local path
uv add ./local-package

# Add editable local package
uv add -e ./local-package

Padrão 5: Removendo Dependências

# Remove package
uv remove requests

# Remove dev dependency
uv remove --dev pytest

# Remove multiple packages
uv remove numpy pandas matplotlib

Padrão 6: Atualizando Dependências

# Atualiza pacote específico
uv add --upgrade requests

# Atualiza todos os pacotes
uv sync --upgrade

# Atualiza pacote para a versão mais recente

…