Dominando a Ferramenta UV

Roger Sampaio

há 55 minutos

5 min de leitura

Olá meus guerreiros. Estou recém-contratado no Banco Inter, conhecendo inicialmente o leque de ferramentas passados no processo de onboarding e confesso que já no primeiro me deparei com tecnologias novas como, por exemplo, a ferramenta UV. Quem nunca perdeu longas horas lidando com conflitos no requirements.txt, tentando alinhar a versão exata do Python ou esperando minutos intermináveis para instalar dependências pesadas em um projeto? Configurar o ambiente de desenvolvimento em Python tradicionalmente pode ser uma verdadeira dor de cabeça. Mas e se eu te disser que existe uma ferramenta moderna, escrita em Rust, capaz de unificar e acelerar todo esse processo? Conheça o uv, desenvolvido pela Astral, que chegou para revolucionar o ecossistema Python.

Neste vídeo, explico exatamente o que é o uv e apresento os comandos essenciais para otimizar o seu fluxo de trabalho. Vamos explorar o leque completo de funcionalidades que tornam essa ferramenta indispensável:

🐍 Gerenciamento de Versões do Python: Esqueça o trabalho manual de baixar e configurar interpretadores. O uv permite instalar, alternar e gerenciar múltiplas versões do Python de forma nativa e instantânea na sua máquina.
⚡ Ambientes Virtuais Ultrarrápidos: Esqueça a lentidão ao criar pastas .venv. Com o uv, a inicialização de ambientes virtuais isolados acontece em milissegundos.
📦Gerenciamento de Pacotes e Dependências: Uma alternativa extremamente rápida, moderna e compatível com os padrões existentes para resolver, baixar e instalar dependências, substituindo ferramentas tradicionais com extrema eficiência.

Assista ao vídeo, simplifique o seu desenvolvimento e ganhe produtividade no seu dia a dia! 🔥

https://youtu.be/YFzlqixUlmw

Os principais comandos podem ser encontrados abaixo.

0. Instalação do uv

Para começar a aproveitar toda a velocidade do uv, o primeiro passo é instalá-lo no seu sistema operacional. Abra o seu terminal de preferência e siga os passos abaixo:

🪟 Ambiente Windows

Abra o PowerShell no modo Administrador e execute o comando de instalação:

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

Caso o comando não reconheça o uv diretamente no terminal, adicione a variável de ambiente temporariamente (ou configure nas variáveis de sistema):

$env:Path = "C:\Users\roger\.local\bin;$env:Path"

🪟 Ambiente macOS

Abra o Terminal e execute o script de instalação oficial:

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

Se necessário, carregue a variável de ambiente manualmente:

source $HOME/.local/bin/env

✅ Verificando a Instalação

Para confirmar que tudo correu bem, verifique a versão instalada:

uv --version

1. Criando a Estrutura do Projeto

Esqueça a criação manual de arquivos de configuração. Com um único comando, o uv inicializa um projeto estruturado:

uv init --python 3.12 nome_projeto

Isso cria automaticamente os arquivos essenciais:

pyproject.toml: O arquivo de configuração principal onde ficam as metadados e dependências do projeto.
uv.lock: Gerenciado automaticamente para garantir o versionamento determinístico e travamento exato das dependências instaladas.

Entre na pasta do projeto recém-criado para continuar:

cd nome_projeto

2. Gerenciando Ambientes Virtuais (.venv)

Embora o uv gerencie dependências de forma automática, você pode criar e controlar o ambiente virtual explicitamente quando precisar:

Criar o ambiente virtual:

uv venv --python 3.12

Ativar o ambiente virtual:

source .venv/bin/activate

Desativar o ambiente virtual:

deactivate

Apagar todo o ambiente virtual:

rm -rf .venv

3. Controle de Versão do Python

Definir e validar a versão do Python no projeto é extremamente simples:

Fixar a versão do Python no projeto:

uv python pin 3.12

Verificar a versão ativa:

python --version

Executar comando usando o Python gerenciado pelo uv:

uv run python --version

Verificar o caminho do interpretador em uso:

which python

4. Gerenciamento de Pacotes e Dependências

O verdadeiro superpoder do uv está na velocidade impressionante para baixar, resolver e instalar pacotes. Veja os principais comandos do dia a dia:

🔄 Sincronizando o Projeto (requirements.txt moderno)

Para instalar todas as dependências listadas no projeto (equivalente a um requirements.txt ou pyproject.toml):

uv sync

➕ Adicionando Dependências

Para adicionar uma nova biblioteca ao projeto (atualiza automaticamente o pyproject.toml e o uv.lock):

uv add pandas matplotlib ipykernel

📦 Instalação Isolada (Sem alterar arquivos de configuração)

Se você precisar instalar um pacote de forma avulsa sem registrar no projeto:

uv pip install pandas

🗑️ Removendo um Pacote

Para desinstalar e remover a dependência do projeto:

uv remove pandas

🔍 Consultando Detalhes de um Pacote

Para inspecionar uma biblioteca instalada:

uv pip show pandas

🚀 Executando Scripts Python

Execute scripts dentro do contexto do ambiente virtual sem precisar ativá-lo manualmente antes:

uv run python caminho_arq/arq.py

Faça download dos principais comandos aqui.

Como complemento para verificar que realmente você aprendeu, brinque com Quiz.

🧠 Quiz Rápido: Teste seus conhecimentos com o uv no Inter!

Responda às questões abaixo para garantir que você está pronto para rodar seus projetos no padrão do time. (Gabarito no final!)

📌 Questão 1: O Primeiro Dia e o Projeto Novo

Você acabou de receber o desafio de criar um novo modelo de Machine Learning para a tribo de Cartões. Para manter a padronização do time com Python 3.12, qual é o primeiro comando que você deve rodar no terminal para inicializar a estrutura do projeto?

[ ] A) pip install python3.12 projeto_cartoes

[ ] B) uv init --python 3.12 projeto_cartoes

[ ] C) uv venv create --version 3.12

[ ] D) python -m venv 3.12 projeto_cartoes

📌 Questão 2: Clonando o Repositório do Time

Um colega de equipe te compartilhou o repositório de um projeto de Prevenção à Fraude. O código usa pyproject.toml e uv.lock. Após clonar o projeto e criar seu ambiente virtual, qual comando você roda para instalar exatamente todas as dependências necessárias de forma idêntica e rápida?

[ ] A) uv sync

[ ] B) uv pip install -r requirements.txt

[ ] C) uv update all

[ ] D) uv add --all

📌 Questão 3: A Biblioteca Certa na Versão Certa

Durante a análise de churn do Inter Loop, você precisa adicionar a biblioteca tqdm na versão específica 4.66.1 para acompanhar o progresso do processamento de dados, garantindo que essa dependência seja registrada no pyproject.toml. Qual comando você deve usar?

[ ] A) uv install tqdm-4.66.1

[ ] B) uv pip install tqdm==4.66.1

[ ] C) uv add tqdm==4.66.1

[ ] D) uv add --version 4.66.1 tqdm

📌 Questão 4: Rodando o Script sem "Quebrar" o Ambiente Global

Você escreveu o script score_credito.py dentro do projeto. Para garantir que ele seja executado utilizando o ambiente virtual isolado do projeto (e suas dependências específicas), como você dispara a execução?

[ ] A) uv run python score_credito.py

[ ] B) python global score_credito.py

[ ] C) uv execute score_credito.py

[ ] D) run .venv score_credito.py

📌 Questão 5: Ajustando Dependências

Você percebeu que uma biblioteca instalada anteriormente para testes não é mais necessária no projeto do time. Qual é a forma recomendada de removê-la e atualizar automaticamente os arquivos de configuração do projeto?

[ ] A) uv delete <nome_pacote>

[ ] B) uv remove <nome_pacote>

[ ] C) pip uninstall <nome_pacote>

[ ] D) Deletar a pasta do pacote manualmente dentro de .venv/

🔑 Gabarito e Explicações

Resposta B: uv init --python 3.12 projeto_cartoes

Por quê? Ele cria a pasta, a estrutura inicial e já configura o pyproject.toml na versão correta do Python.

Resposta A: uv sync

Por quê? O uv sync lê o arquivo de lock e sincroniza o ambiente virtual, garantindo consistência total entre as máquinas do time.

Resposta C: uv add tqdm==4.66.1

Por quê? O uv add instala o pacote e atualiza automaticamente a lista de dependências do projeto no pyproject.toml (o uv pip install apenas instalaria isoladamente sem salvar a dependência no arquivo do projeto).

Resposta A: uv run python score_credito.py

Por quê? O uv run executa qualquer comando utilizando o contexto e o ambiente virtual correto do projeto.

Resposta B: uv remove <nome_pacote>

Por quê? Além de desinstalar do ambiente virtual, o uv remove limpa a referência do pacote no pyproject.toml e no uv.lock.