DEV Community

Francisco Júnior
Francisco Júnior

Posted on

Dominando o uv: O Sucessor do Pip, Poetry e Pyenv

#uv #python #ambiente

O uv (construído pela Astral, os criadores do Ruff) não é apenas um instalador de pacotes mais rápido. Ele é um gerenciador de projetos Python unificado escrito em Rust.

O Problema que ele resolve:
Antigamente, você precisava de uma "salada de frutas" de ferramentas:

  • pyenv para instalar versões do Python.
  • virtualenv ou venv para criar ambientes.
  • pip para instalar pacotes.
  • pip-tools para gerar lockfiles.
  • pipx para rodar ferramentas CLI (como black, ruff).
  • poetry ou pdm para gerenciar projetos complexos.

A Solução uv:
O uv substitui todas as ferramentas acima com um único binário estático, 10-100x mais rápido.

1. Instalação e Configuração

Não instale via pip. O uv deve viver fora do ambiente Python para poder gerenciar o próprio Python.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Enter fullscreen mode Exit fullscreen mode

Pós-Instalação (Crucial):
Habilite o autocompletar no seu shell e mantenha-o atualizado.

# Adicionar ao ~/.zshrc ou ~/.bashrc
eval "$(uv generate-shell-completion zsh)"

# Para atualizar o uv no futuro
uv self update
Enter fullscreen mode Exit fullscreen mode

2. Gerenciamento de Projetos (O Novo Padrão)

Esqueça o requirements.txt manual. O uv usa o padrão moderno pyproject.toml.

2.1 Iniciando um Projeto 

# Cria uma pasta com estrutura padrão
uv init meu-projeto-dados
cd meu-projeto-dados

# O que ele cria:
# - .python-version (versão do python fixada)
# - pyproject.toml (dependências)
# - hello.py (exemplo)
Enter fullscreen mode Exit fullscreen mode

2.2 Adicionando Dependências

Isso adiciona a lib ao pyproject.toml E atualiza o arquivo de trava uv.lock automaticamente.

# Adiciona bibliotecas de produção
uv add pandas polars

# Adiciona bibliotecas apenas de desenvolvimento (ex: testes, linters)
uv add --dev pytest ruff
Enter fullscreen mode Exit fullscreen mode

2.3 Sincronização (uv sync)

Se você clonou um repo ou mudou de branch, rode isso. O comando garante que seu ambiente virtual (.venv) esteja exatamente igual ao uv.lock.

uv sync
Enter fullscreen mode Exit fullscreen mode

3. Gerenciamento de Versões Python (Adeus, Pyenv)

Esta é a "killer feature". O uv baixa e instala versões do Python automaticamente, sem compilar nada, em segundos.

Instalar uma versão específica:

uv python install 3.12
Enter fullscreen mode Exit fullscreen mode

Ver versões disponíveis:

uv python list
Enter fullscreen mode Exit fullscreen mode

Fixar versão no projeto:

uv python pin 3.11
# Isso cria um arquivo .python-version. O uv usará essa versão automaticamente neste projeto.
Enter fullscreen mode Exit fullscreen mode

Nota: Se você rodar uv run em um projeto que pede Python 3.13 e você não o tem, o uv baixa, instala e configura o ambiente na hora, sem perguntar.

4. Scripts e Execução Ad-Hoc

Para Data Science e Scripts de Automação, o uv brilha com suporte ao PEP 723 (Inline Script Metadata).

Imagine que você tem um script analise.py solto. Você não precisa criar um projeto inteiro para ele.

Arquivo: `analise.py`

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
#     "pandas",
# ]
# ///
import requests
import pandas as pd
print("Rodando com dependências isoladas!")
Enter fullscreen mode Exit fullscreen mode

Como rodar:

uv run analise.py
Enter fullscreen mode Exit fullscreen mode

O uv cria um ambiente virtual temporário, instala requests e pandas, roda o script e limpa (ou cacheia) depois. É perfeito para compartilhar scripts entre o time sem "Funciona na minha máquina".

5. Ferramentas Globais (Adeus, Pipx)

Para ferramentas que você usa no terminal (CLI), não instale no projeto, instale na "tool chain".

Instalar fixo (ex: Ruff, Black, CLI da AWS):

uv tool install ruff
uv tool install awscli
Enter fullscreen mode Exit fullscreen mode

Executar sem instalar (Efêmero):
Use uv x (alias para uv tool run).

# Baixa o ruff, roda a checagem e sai.
uv x ruff check .

# Inicia um Jupyter Lab instantâneo
uv x jupyter lab
Enter fullscreen mode Exit fullscreen mode

6. Fluxo de Migração

De pip (requirements.txt) para uv

Você pode continuar usando o pip style se quiser (modo legado), mas o ideal é migrar.

# Modo Legado (apenas instala rápido)
uv pip install -r requirements.txt

# Migração para Moderno (Gera pyproject.toml)
uv init
uv add -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

De Poetry para uv

O uv entende o formato do Poetry nativamente em muitos casos, mas a migração recomendada é converter para o padrão oficial.

  1. Apague o poetry.lock.
  2. Renomeie a seção [tool.poetry.dependencies] para [project.dependencies] no toml (ou deixe o uv recriar).
  3. Rode uv lock.

7. Docker e CI/CD (Otimização Extrema)

O uv reduz drasticamente o tempo de build de containers.

Dockerfile Otimizado:

FROM python:3.12-slim-bookworm

# Instala uv (copiando binário da imagem oficial - Padrão Ouro)
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

WORKDIR /app

# 1. Copia apenas os arquivos de definição
COPY pyproject.toml uv.lock ./

# 2. Instala dependências (usando cache de montagem se possível)
# --frozen: Falha se o lockfile estiver desatualizado (segurança)
# --no-install-project: Instala só as libs, não o código do projeto ainda
RUN uv sync --frozen --no-install-project

# 3. Copia o resto do código
COPY . .

# 4. Instala o projeto
RUN uv sync --frozen

# O uv coloca o venv em .venv automaticamente. Adicione ao PATH.
ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "main.py"]
Enter fullscreen mode Exit fullscreen mode

Resumo dos Comandos Essenciais

Ação Comando Antigo (pip/venv) Comando uv
Criar Ambiente python -m venv .venv uv venv (Opcional, uv init faz automático)
Instalar Pacote pip install pandas uv add pandas
Remover Pacote pip uninstall pandas uv remove pandas
Atualizar Tudo (Complexo/Manual) uv lock --upgrade
Rodar Script source .venv/bin/activate && python app.py uv run app.py
Listar Árvore pipdeptree uv tree
Instalar Python pyenv install 3.12 uv python install 3.12
Limpar Cache pip cache purge uv cache clean

Dica de Ouro: O Cache

O uv usa "Hardlinks". Se você tem 10 projetos usando pandas==2.2.0, o uv armazena o arquivo apenas uma vez no disco. Todos os seus ambientes virtuais compartilham esse arquivo físico. Isso economiza GBs de espaço em disco instantaneamente.

Top comments (0)