Artigo 2 — Gerenciando Ambientes Python com o Astral UV

(Série: Construindo Projetos Python de Forma Profissional — Parte 2/4)

Por Leonardo Souza — Engenheiro de Software e Sistemas Embarcados

Introdução

Este é o segundo artigo da série, onde estamos construindo um projeto Python moderno, organizado e alinhado às práticas do mercado.

Se você não leu o primeiro, recomendo fazê-lo antes, pois nele explico o porquê da série e como ela será estruturada.

https://web.dio.me/articles/construindo-projetos-python-de-forma-profissional-introducao-a-serie-de-3-artigos-f205b6a05855?back=/articles

Neste artigo vamos trabalhar a fundação de qualquer projeto Python profissional:

o gerenciamento do ambiente e das dependências com o Astral UV.

Nada de pip install solto, criação de requirements.txt e/ou outras formas de gerenciar o ambiente do projeto.

Nada de virtualenv espalhado na máquina.

Aqui o ambiente é isolado, reproduzível e controlado.

O que é o Astral UV

O UV é um gerenciador de pacotes e ambientes Python, veja abaixo a comparação:

Principais Vantagens

• Rápido na instalação e resolução de dependências
• Ambientes isolados por projeto (sem poluir o sistema)
• Reprodutibilidade garantida pelo uv.lock
• Código organizado desde o início

Documentação oficial:

Site oficial: Astral UV

Repositório: https://github.com/astral-sh/uv

Instalação

Caso o uv não seja reconhecido no Linux (Adicionar ao PATH)

1. Abra o arquivo .bashrc:

nano ~/.bashrc

1. Vá até o final do arquivo e adicione:

export PATH="$HOME/.local/bin:$PATH"

1. Salvar e sair do nano:

• Ctrl + O → Enter (salva o arquivo)
• Ctrl + X (fecha o editor)

1. Recarregar as configurações:

source ~/.bashrc

1. Testar:

uv --version

Se aparecer algo como uv 0.8.x, está configurado corretamente ✅

Windows

Descrição:

O comando abaixo executa o instalador em PowerShell, adicionando o uv ao PATH automaticamente.

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

Verifique a instalação:

uv --version

Caso o comando não funcione, feche e abra novamente o terminal ou adicione o diretório do UV ao PATH.

Inicializando um Projeto

Vamos criar um projeto que será usado até o final da série:

uv init meuprojetoapi
cd meuprojetoapi

Estrutura gerada:

meuprojetoapi/
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

Observação: o ambiente virtual .venv/ será criado automaticamente ao instalar dependências.

Gerenciamento de Dependências

Adicionar dependências (produção)

Essas vão para o código da aplicação:

uv add fastapi

(Não vamos usar o FastAPI agora — apenas ilustrando. Ele será configurado no Artigo 3.)

Adicionar dependências de desenvolvimento

Essas não vão para produção:

uv add --dev black pytest

Sincronizar dependências após clonar o projeto

uv sync

Executando o Projeto

Execute:

uv run main.py
Hello from meuprojetoapi!

Sem ativar virtualenv manual.

Sem pip.

Sem confusão.

Boas Práticas

Conclusão

Agora você possui a base sólida para trabalhar em projetos Python com organização e previsibilidade.

Com o UV, você:

• Estrutura o projeto corretamente
• Mantém o ambiente isolado
• Controla dependências com rastreabilidade
• Evita conflitos entre máquinas e desenvolvedores

Essa é a fundação necessária para o próximo passo.

Próximo Artigo (Parte 3/4)

Criando uma API Moderna com FastAPI (Dentro do Projeto UV)

Nele vamos:

• Instalar e configurar FastAPI corretamente
• Criar a primeira rota
• Rodar o servidor
• Utilizar o Swagger automático

Agora que o terreno está preparado, vamos começar a construir.

LINKS com os artigos da serie:

Artigo 1 - Construindo Projetos Python de Forma Profissional: Introdução à Série de 3 Artigos:

https://web.dio.me/articles/construindo-projetos-python-de-forma-profissional-introducao-a-serie-de-3-artigos-f205b6a05855?back=/articles

Artigo 3 — Criando uma API Moderna com FastAPI (Dentro do Projeto com UV)

https://web.dio.me/articles/artigo-3-criando-uma-api-moderna-com-fastapi-dentro-do-projeto-com-uv-31a4bf890458