Gerenciando Ambientes Python com o Astral UV

Por Leonardo — Engenheiro de Software e Sistemas Embarcados, com 8 anos de experiência em desenvolvimento e integração de sistemas.

Introdução

O Astral UV é uma ferramenta moderna para gerenciamento de dependências e ambientes Python. Neste artigo, apresento um guia completo sobre sua instalação, configuração e uso, com exemplos práticos integrando o FastAPI. O objetivo é fornecer uma visão clara e organizada para desenvolvedores que desejam manter projetos Python consistentes, reprodutíveis e fáceis de gerenciar.

O que é o Astral UV

O UV é um gerenciador de pacotes e ambientes Python que simplifica a vida do desenvolvedor. Ele unifica funções de ferramentas tradicionais como pip, venv e poetry, automatizando a criação e manutenção de ambientes virtuais, instalação de dependências e execução de scripts.

Principais benefícios:

• Velocidade e confiabilidade: UV é otimizado para instalar dependências rapidamente.
• Isolamento de ambiente: Cria automaticamente .venv garantindo que cada projeto seja independente.
• Reprodutibilidade: O arquivo uv.lock garante que todas as máquinas usem exatamente as mesmas versões de pacotes.

Documentação oficial: https://astral.sh/uv

Instalação

Linux

No Linux, a instalação é feita via shell script. Ele adiciona automaticamente o binário uv ao PATH:

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

Verifique se a instalação foi concluída corretamente:

uv --version

Saída esperada:

uv 0.8.17

Windows

No Windows, a instalação é realizada através do PowerShell:

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

Verifique a versão instalada:

uv --version

Dica: Caso o comando não seja reconhecido, reinicie o terminal ou adicione o diretório do UV ao PATH do sistema.

Inicializando um Projeto

O comando uv init cria toda a estrutura inicial de um projeto Python gerenciado pelo UV:

uv init

Para usar uma versão específica do Python:

uv init --python 3.12

Arquivos criados:

Observação: O ambiente virtual (.venv/) é criado automaticamente na primeira instalação de dependência.

Gerenciamento de Dependências

O UV substitui pip e requirements.txt com comandos intuitivos e reprodutíveis.

Adicionar dependências:

uv add flask

Remover dependências:

uv remove flask

Adicionar dependências de desenvolvimento:

uv add --dev black

Sincronizar dependências (após clonar um repositório):

uv sync

Executar comandos dentro do ambiente virtual:

uv run black .

Executando o Projeto

Para rodar o script principal:

uv run main.py

Para projetos que usam frameworks como FastAPI:

uv run fastapi dev main.py

O comando uv run garante que a execução use o ambiente virtual correto, evitando conflitos de versão.

Integrando com FastAPI

Criando um projeto FastAPI

1. Inicialize o projeto:

uv init hello_fastapi
cd hello_fastapi

1. Instale as dependências principais:

uv add "fastapi[standard]"

1. Instale dependências de desenvolvimento:

uv add --dev pytest black

Abra o projeto no VSCode:

code .

Hello World FastAPI

Crie um arquivo main.py com o seguinte conteúdo:

from fastapi import FastAPI

app = FastAPI(title="Hello FastAPI")

@app.get("/")
def hello_world():
  return {"message": "Hello World!"}

Execute o servidor de desenvolvimento:

uv run fastapi dev main.py

Saída esperada:

INFO:     Started server process [1234]
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Acesse no navegador:

http://127.0.0.1:8000

Boas Práticas

1. Versionamento

• Inclua sempre pyproject.toml e uv.lock no controle de versão.
• Não versionar .venv/.

1. Sincronização

• Após clonar repositórios, use uv sync para instalar dependências corretas.

1. Execução

• Prefira uv run em vez de python para garantir o uso do ambiente virtual.

1. Dependências de desenvolvimento

• Utilize --dev para pacotes que não vão para produção, como testes e formatadores.

1. Reprodutibilidade

• O uv.lock garante que qualquer máquina use exatamente as mesmas versões de pacotes.
• Evite editar o uv.lock manualmente.

Conclusão

O Astral UV é uma ferramenta prática e poderosa para quem trabalha com Python e quer manter projetos organizados, consistentes e fáceis de gerenciar. Com ele, criar ambientes, instalar dependências e rodar scripts se torna muito mais rápido e confiável.

Ao integrar com frameworks como FastAPI, você ganha ainda mais agilidade no desenvolvimento de APIs modernas. Experimente explorar os comandos do UV e adapte-o ao seu fluxo de trabalho — com o tempo, ele se torna um aliado indispensável no dia a dia de qualquer desenvolvedor.

A maioria desses conceitos eu aprendi com o Davi Lucciola, aqui em BH, que me apresentou boas práticas e formas eficientes de trabalhar com Python e gerenciamento de ambientes.

Agora é só colocar a mão na massa e aproveitar todas as vantagens do UV nos seus projetos Python!

• Material de apoio - https://youtu.be/wD1Trf45ScI?si=qDxlqyHEg-l5R0IP