Skip to content

MIGRACAO_PIP_UV

Jump to bottom
Ysrael edited this page May 10, 2026 · 1 revision

📚 Guia de Migração: Pip → UV

Resumo Executivo

UV é um gerenciador de pacotes Python ultra-moderno escrito em Rust que oferece:

  • ⚡ 10-100x mais rápido que pip
  • 🔒 Lock file seguro (uv.lock) para versões determinísticas
  • 🐍 Gerenciamento nativo de versões Python
  • 📦 Padrão moderno: PEP 517/518 (pyproject.toml)
  • 🎯 100% compatível com pip e requirements.txt

Comparação: Pip vs UV

1. Instalação de Dependências

Com Pip (Antigo)

# 1. Criar ambiente virtual
python -m venv .venv

# 2. Ativar (Windows)
.\.venv\Scripts\Activate.ps1

# 3. Instalar
pip install -r requirements.txt

# ⏱️  Tempo: ~15-30 segundos

Com UV (Moderno)

# 1. Sync automático (tudo em 1 comando!)
uv sync

# ⏱️  Tempo: ~1-3 segundos (10-20x mais rápido!)

2. Estrutura de Arquivos

Antes (Pip)

projeto/
├── setup.py              # Build script antigo
├── requirements.txt      # Dependências sem lock
├── requirements-dev.txt  # Dev deps
└── .venv/              # Ambiente virtual

Depois (UV + Modern Python)

projeto/
├── pyproject.toml       # Configuração moderna (PEP 517/518)
├── uv.lock             # Lock file determinístico
├── requirements.txt    # OPCIONAL (compatibilidade)
├── setup.py           # OPCIONAL (compatibilidade)
└── .venv/             # Ambiente virtual

3. Adicionar Dependência

Pip

pip install novo-pacote
# ⚠️  Não atualiza requirements.txt automaticamente
# Precisa fazer manualmente:
pip freeze > requirements.txt

UV

uv add novo-pacote
# ✅ Atualiza automaticamente pyproject.toml + uv.lock

4. Remover Dependência

Pip

pip uninstall novo-pacote
pip freeze > requirements.txt
# ⚠️  Manual e propenso a erros

UV

uv remove novo-pacote
# ✅ Automático

5. Lock File

Pip

❌ Não há lock file padrão
❌ Versões podem variar entre máquinas
❌ pip freeze cria lista, mas não é confiável

UV

✅ uv.lock cria lock file determinístico
✅ Versões garantidas em todas as máquinas
✅ Compatível com git (versionável)

6. Execução de Scripts

Pip

# Precisa ativar manualmente
source .venv/bin/activate  # Linux/Mac
.\.venv\Scripts\Activate.ps1  # Windows

python script.py

UV

# Executa diretamente (sem ativar!)
uv run python script.py

7. Gerenciar Versões Python

Pip

# ❌ Não gerencia Python
# Precisa de pyenv ou manual
pyenv install 3.11
pyenv local 3.11
python -m venv .venv

UV

# ✅ Gerencia automaticamente
uv python install 3.11
uv sync --python 3.11

Tabela Comparativa Detalhada

Característica Pip UV
Velocidade ~15-30s ~1-3s
Lock file ❌ ✅ uv.lock
Determinístico ❌ ✅
Python nativo ❌ ✅
Cache paralelo ❌ ✅
Padrão moderno ❌ ✅ PEP 517/518
Suporte pip ✅ ✅
Workspace ❌ ✅ (Monorepo)
Performance cache Médio Excelente
Comunidade ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐

Instalação do UV

Windows (PowerShell)

# Opção 1: WinGet (Recomendado)
winget install astral-sh.uv

# Opção 2: Python (Fallback)
pip install uv

# Verificar
uv --version

macOS

# Opção 1: Homebrew (Recomendado)
brew install uv

# Opção 2: Curl
curl -LsSf https://astral.sh/uv/install.sh | sh

# Opção 3: Python
pip install uv

Linux

# Opção 1: Curl (Recomendado)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Opção 2: Package Manager (APT, YUM, etc)
# https://docs.astral.sh/uv/guides/installation/

# Opção 3: Python
pip install uv

Migrando um Projeto Existente

Passo 1: Entender Estrutura Atual

# Ver dependências atuais
cat requirements.txt
cat requirements-dev.txt  # Se existir

Passo 2: Instalar UV

# Windows
winget install astral-sh.uv

# macOS
brew install uv

# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Passo 3: Criar pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "meu-projeto"
version = "1.0.0"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.25.0",
    "python-dotenv>=0.19.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
]

Passo 4: Migrar Dependências

# Opção A: Manual (mais controle)
# Copie dados de requirements.txt para pyproject.toml

# Opção B: Automático com UV
uv pip compile requirements.txt -o requirements-compiled.txt
# Depois copie para pyproject.toml

# Opção C: Do zero (recomendado)
uv sync  # UV irá ler requirements.txt e criar pyproject.toml

Passo 5: Sincronizar

# Cria .venv e instala tudo
uv sync

# Instala apenas prod (sem dev)
uv sync --no-dev

# Com grupo específico
uv sync --group dev

Passo 6: Atualizar Scripts

Antes:

source .venv/bin/activate
python script.py

Depois:

uv run python script.py

Passo 7: Committar Mudanças

git add pyproject.toml uv.lock
git remove setup.py requirements.txt  # Opcionais agora
git commit -m "chore: migrate to uv package manager"

Comandos UV Essenciais

Instalação e Sync

uv sync                    # Instala tudo
uv sync --no-dev          # Sem dev dependencies
uv sync --refresh         # Ignora cache
uv sync --python 3.11     # Com Python específico

Gerenciar Pacotes

uv add requests            # Adiciona dependência
uv add -d pytest           # Adiciona dev dependency
uv remove requests         # Remove dependência
uv pip install requests    # Compatibilidade pip
uv pip show requests       # Info do pacote

Executar Código

uv run python script.py    # Executa script
uv run pytest             # Roda testes
uv run python -c "..."    # Executa comando
uv run --help             # Ajuda

Ambientes Virtuais

uv venv                    # Cria .venv
uv venv --python 3.11     # Com Python específico
source .venv/bin/activate # Ativa (Linux/Mac)
.\.venv\Scripts\Activate.ps1 # Ativa (Windows)

Python

uv python list            # Versões disponíveis
uv python install 3.11    # Instala versão
uv python find 3.11       # Encontra versão

Limpeza

uv cache clean            # Limpa cache local
uv cache prune            # Remove entradas antigas

FAQ - Migração Pip → UV

P: Preciso desinstalar pip?

R: Não! UV é compatível com pip. Você pode usar ambos.

P: Como faço rollback para pip?

R: UV cria um pyproject.toml padrão que pip consegue ler:

pip install .
pip install -e .

P: Meu projeto usa setup.py, devo manter?

R: Não é obrigatório. pyproject.toml é o padrão moderno. Mas pip ainda lê setup.py, então é seguro depreciar gradualmente.

P: Como faço versionamento de dependências com UV?

R: UV gera uv.lock automaticamente com versions pinadas. Versione-o no git como qualquer arquivo.

P: Posso usar diferentes versões Python?

R: Sim! UV gerencia versões Python nativamente:

uv sync --python 3.10
uv sync --python 3.11

P: Como integro com CI/CD?

R: GitHub Actions:

- uses: astral-sh/setup-uv@v1
- run: uv sync
- run: uv run pytest

P: Qual a vantagem do uv.lock?

R: Garante que em todas as máquinas (dev, CI, produção) as versões sejam exatamente as mesmas.

P: UV suporta extras/optional dependencies?

R: Sim!

[project.optional-dependencies]
dev = ["pytest"]
docs = ["sphinx"]
uv sync --group dev
uv add "pacote[extra]"

Próximas Leituras

Checklist de Migração

  • Instalar UV
  • Criar pyproject.toml
  • Executar uv sync
  • Testar instalação (uv run python script.py)
  • Gerar uv.lock
  • Atualizar CI/CD
  • Committar pyproject.toml + uv.lock
  • Atualizar documentação
  • Comunicar à equipe
  • Opcional: Remover setup.py e requirements.txt

Bem-vindo ao futuro do Python! 🚀

🗺️ Navigation

Clone this wiki locally