Artigo 2 — Gerenciando Ambientes Python com o Astral UV
- #Python
(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.
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)
- Abra o arquivo
.bashrc:
nano ~/.bashrc
- Vá até o final do arquivo e adicione:
export PATH="$HOME/.local/bin:$PATH"
- Salvar e sair do nano:
Ctrl + O→ Enter (salva o arquivo)Ctrl + X(fecha o editor)
- Recarregar as configurações:
source ~/.bashrc
- 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.
