Como configurar um projeto Python rápido e reproduzível com uv

Quando apontas um agente de programação com IA como o Claude Code ou o Codex para um projeto Python, metade do atrito não tem nada a ver com o modelo. Vem do ambiente: pacotes em falta, a versão errada do Python, um virtualenv que o agente se esqueceu de ativar, ou um colega de equipa para quem "funciona na minha máquina". A solução é um projeto que seja reproduzível por omissão, e a forma mais rápida de obter um hoje é o uv, a cadeia de ferramentas Python baseada em Rust da Astral.

O uv substitui o pip, o venv, o pip-tools e o pyenv por um único comando rápido, e escreve um ficheiro de bloqueio (lockfile) para que exatamente a mesma árvore de dependências seja instalada em todo o lado. Este guia leva-te do zero a um projeto bloqueado e executável em poucos minutos.

Por que é que o ambiente importa para um agente

Um agente de IA executa comandos na tua shell e lê os erros que voltam. Se o teu projeto não tem dependências declaradas nem uma versão fixada do Python, o agente tem de adivinhar — e um palpite errado leva-o a uma espiral de instalar pacotes globalmente ou editar o interpretador errado. Um projeto com um pyproject.toml e um uv.lock dá ao agente uma única fonte de verdade: pode executar uv sync, obter os pacotes certos e seguir em frente. Gastas o teu tempo de revisão na lógica, não em arqueologia de ambientes.

Instalar o uv

No macOS ou no Linux:

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

No Windows (PowerShell):

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

O uv é um único binário autossuficiente, por isso não há mais nada para configurar.

Iniciar um projeto num comando

uv init weather-cli
cd weather-cli

Isto cria a estrutura de um projeto funcional: um pyproject.toml para metadados e dependências, um ficheiro .python-version, um main.py inicial, um README.md e um .gitignore. Não crias nem ativas um virtualenv à mão — o uv gere um .venv por ti no momento em que precisas.

Adicionar dependências (e porque é que o lockfile importa)

uv add requests

Isto faz três coisas ao mesmo tempo: regista o requests no pyproject.toml, resolve a árvore completa de dependências e escreve o uv.lock com versões exatas e fixadas, multiplataforma. Também podes fixar a versão no momento de adicionar:

uv add 'requests==2.31.0'

Faz commit do uv.lock no Git. É a diferença entre "instalar o requests mais recente" (que se desvia com o tempo) e "instalar a árvore exata que testámos". Quando o teu agente — ou o teu CI, ou um novo colega de equipa — executar uv sync, obtém um ambiente idêntico byte a byte.

Executar código sem ativar nada

uv run main.py

O uv run garante que o ambiente está sincronizado e depois executa dentro dele — sem a dança do source .venv/bin/activate. Isto importa especialmente para os agentes: cada chamada de ferramenta é muitas vezes uma shell nova, por isso "ativar e depois executar" falha com frequência, enquanto um único uv run funciona sempre. Podes envolver qualquer comando:

uv run -- pytest -q
uv run -- flask run -p 3000

Fixar uma versão do Python para que o agente e o CI concordem

uv python pin 3.12

Isto escreve a versão no .python-version, e o uv vai descarregar e usar esse interpretador automaticamente — sem necessidade de um Python do sistema. Agora a versão com que desenvolves é a versão que o teu agente, os teus colegas de equipa e o teu CI usam todos.

Um pequeno exemplo prático

Digamos que pedes a um agente para "adicionar um comando que vá buscar a meteorologia de hoje". Com o uv instalado, todo o ciclo é limpo:

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# o agente edita o main.py para chamar uma API...
uv run main.py

O agente nunca tem de raciocinar sobre qual o interpretador ativo ou se o requests está instalado — esses factos estão declarados em ficheiros que ele consegue ler. Se introduzir uma nova dependência, executa uv add e o lockfile atualiza-se. Se algo falhar no CI, o uv sync reproduz o ambiente exato localmente para que o possas depurar.

Para onde caminha o uv

O uv e as suas ferramentas irmãs ruff (linter/formatador) e ty (verificador de tipos) são amplamente adotados — só o uv ultrapassa bem mais de 100 milhões de descargas por mês. Em março de 2026, a OpenAI concordou em adquirir a Astral, a empresa por detrás delas, para integrar a cadeia de ferramentas na sua plataforma Codex, comprometendo-se a manter as ferramentas com licença MIT como código aberto (OpenAI, Simon Willison). Por agora, a conclusão prática mantém-se inalterada: o uv é o caminho mais rápido para um projeto Python sobre o qual o teu agente de IA consegue construir sem adivinhar.

Referência rápida

Tarefa	Comando
Criar um projeto	uv init <name>
Adicionar uma dependência	uv add <package>
Fixar o Python	uv python pin 3.12
Executar código	uv run <file or command>
Reproduzir o ambiente	uv sync
Atualizar o lockfile	uv lock --upgrade-package <pkg>