UV Python: o Guia Completo Para Usar Essa Ferramenta
Aprenda o que é o UV Python, como instalar, criar projetos, gerenciar dependências e ambientes virtuais com mais velocidade e praticidade do que o pip.
O UV é um gerenciador de pacotes e projetos Python escrito em Rust, criado pela Astral, que reúne num único binário o que antes exigia pip, venv e pyenv. Instale com curl -LsSf https://astral.sh/uv/install.sh | sh (no Windows, o script equivalente em PowerShell), inicie o projeto com uv init e adicione bibliotecas com uv add: o ambiente virtual, o pyproject.toml e o lockfile são criados e atualizados sozinhos.
O que você vai ver aqui?
Introdução
Se você trabalha com Python há algum tempo, já deve ter passado pela dor de cabeça de configurar ambiente virtual, instalar pacotes com pip, atualizar o requirements.txt manualmente e ainda torcer para que tudo funcione igual na máquina de outra pessoa.
O UV Python chegou exatamente para resolver isso, reunindo em uma única ferramenta tudo que você precisava de três ou quatro ferramentas diferentes.
Com o UV, você inicializa projetos, instala bibliotecas, gerencia versões do Python e mantém as dependências sempre sincronizadas, tudo de forma automática e muito mais rápida do que o fluxo tradicional. Ele foi criado pela Astral, a mesma empresa por trás do Ruff, e está ganhando cada vez mais espaço na comunidade Python justamente por ser direto ao ponto e fácil de adotar, mesmo em projetos que já existem.
Neste artigo você vai aprender na prática como instalar o UV, criar seu primeiro projeto com ele, gerenciar pacotes e versões do Python e até migrar projetos antigos sem complicação. Se você ainda usa pip e venv do jeito tradicional, é bem provável que depois daqui você queira mudar.
O que é o UV Python e por que ele está substituindo o pip?
Se você já trabalhou em projetos Python com mais de uma biblioteca, sabe que o gerenciamento de dependências pode virar uma bagunça rapidamente. O pip instala os pacotes, mas não cria o ambiente virtual. O venv cria o ambiente, mas não gerencia versões do Python. O pyenv cuida das versões, mas não fala com o pip. No fim, você acaba orquestrando três ferramentas ao mesmo tempo para fazer algo que deveria ser simples.
O UV chega para resolver exatamente isso. Ele é um gerenciador de pacotes e projetos Python que centraliza tudo em um único lugar, permitindo que você instale bibliotecas, crie ambientes virtuais, gerencie versões do Python e mantenha as dependências sempre sincronizadas, com uma velocidade muito acima do que o pip consegue entregar.
Quem criou o UV e qual tecnologia está por trás?
O UV foi desenvolvido pela Astral, a mesma empresa responsável pelo Ruff, que é um linter e formatador de código Python extremamente rápido. O objetivo da Astral com o UV é construir o que eles chamam de “Cargo para Python”, ou seja, um gerenciador de projetos e pacotes completo, rápido, confiável e fácil de usar, nos mesmos moldes do que o Cargo representa para o ecossistema Rust.
O UV é escrito em Rust e foi projetado como um substituto direto para ferramentas como pip e pip-tools. Ser escrito em Rust é justamente o que explica boa parte do ganho de velocidade: o UV não depende do Python para funcionar, e toda a lógica de resolução e instalação de pacotes é executada de forma nativa, sem a sobrecarga de um interpretador.
Saiba mais sobre o projeto na Documentação oficial do UV.
O que o UV faz que o pip não faz
O pip é uma ferramenta focada em uma coisa só: instalar pacotes. Qualquer coisa além disso exige ferramentas adicionais. O UV, por sua vez, consolida em um único binário tudo que você precisaria de várias ferramentas separadas. Veja o que ele cobre:
- Instalação de pacotes, como o pip faz, mas com velocidade muito superior e cache global inteligente
- Criação e gerenciamento de ambientes virtuais, sem precisar do venv ou do virtualenv
- Gerenciamento de versões do Python, sem precisar do pyenv
- Lockfile automático, algo que o pip não tem nativamente e que exigiria o pip-tools para alcançar
- Inicialização de projetos com estrutura padrão já configurada
Desde seu lançamento inicial como substituto do pip, o UV foi expandido para se tornar uma solução completa para gerenciar projetos Python, ferramentas de linha de comando, scripts de arquivo único e até o próprio Python.
Como Instalar o UV Python no seu Computador
Antes de qualquer coisa, é importante saber que o UV não vem instalado por padrão no Python. Você precisa instalá-lo manualmente, e o processo é bem simples.
Instalação no Windows, Mac e Linux
O método recomendado pela própria Astral é usar o instalador standalone, que não exige nem Rust nem Python previamente instalado. Os comandos variam conforme o sistema operacional:
No Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"No Mac e Linux (terminal):
curl -LsSf https://astral.sh/uv/install.sh | shDepois de rodar o comando, é fundamental reiniciar o terminal antes de continuar. Se você estiver usando o terminal integrado do VS Code, feche o editor completamente e abra novamente, para que a instalação seja reconhecida corretamente.
Caso tenha alguma dúvida com o processo, você pode seguir o Guia completo de instalação do UV.
Instalação via pip (método alternativo)
Sim, é um pouco irônico instalar pelo pip uma ferramenta que veio para substituí-lo, mas funciona. Se você já tem o pip configurado e prefere esse caminho, basta rodar:
pip install uvQuando o UV é instalado via PyPI, a recomendação é que ele seja instalado em um ambiente isolado, por exemplo usando pipx, para evitar conflitos com outros pacotes. Para a maioria dos usos cotidianos, porém, a instalação direta funciona sem problemas.
Python ImpressionadorVocê vai aprender a linguagem de Programação que mais cresce no Mundo para fazer automações incríveis, desenvolver sites, fazer análises de dados, trabalhar com Ciência de Dados, Inteligência Artificial, mesmo que você nunca tenha tido nenhum contato com Programação na vida.
Começar agora
Como Criar um Projeto com UV do Zero
Com o UV instalado, você já pode começar a criar projetos. E aqui está uma das primeiras grandes diferenças em relação ao fluxo tradicional: você não precisa criar manualmente a pasta, inicializar o git, criar o ambiente virtual e configurar os arquivos do projeto. O UV faz tudo isso com um único comando.
O comando uv init e os arquivos criados automaticamente
Abra o terminal na pasta onde você quer criar o projeto e rode:
uv init nome-do-projetoSe você já estiver dentro da pasta do projeto, pode rodar apenas uv init sem passar o nome. Em segundos, o UV vai criar a seguinte estrutura:
novo-projeto/
├── .git/
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.mdPerceba que ele já inicializa o repositório git, cria o .gitignore com configurações padrão e entrega um main.py pronto para você começar a escrever código. Isso poupa aqueles primeiros minutos que você normalmente perde configurando o projeto antes de fazer qualquer coisa útil.
O que é o pyproject.toml e como ele substitui o requirements.txt
O arquivo pyproject.toml é o coração do seu projeto quando você usa o UV. Enquanto o requirements.txt era um arquivo que você precisava atualizar manualmente a cada nova biblioteca instalada, o pyproject.toml é mantido automaticamente pelo UV.
Toda vez que você adiciona ou remove uma biblioteca, o UV atualiza esse arquivo sozinho. Ele registra a versão do Python exigida pelo projeto, todas as dependências diretas e as restrições de versão de cada uma. Nada de pip freeze > requirements.txt manual.
Além disso, o formato .toml é amplamente reconhecido por servidores e plataformas modernas de deploy, o que facilita bastante quando você for colocar seu projeto em produção.
Entenda o pyproject.toml com detalhes na documentação oficial.
O que é o uv.lock e por que ele garante reprodutibilidade
Junto com o pyproject.toml, o UV cria um segundo arquivo chamado uv.lock. Esse arquivo é o que garante que o seu projeto vai funcionar exatamente igual em qualquer máquina.
A diferença entre os dois é importante: enquanto o pyproject.toml declara as dependências de forma geral (por exemplo, “preciso do FastAPI na versão 0.100 ou superior”), o uv.lock registra as versões exatas de tudo que foi instalado, incluindo as dependências das dependências.
O uv.lock é um lockfile universal e multiplataforma que captura todos os pacotes que seriam instalados em qualquer combinação de sistema operacional, arquitetura e versão do Python. Esse arquivo deve ser incluído no controle de versão, permitindo instalações consistentes e reproduzíveis em qualquer máquina.
Na prática, isso significa que se uma dependência indireta do FastAPI lançar uma atualização que cause conflito, o seu projeto não vai ser afetado, porque o uv.lock garante que exatamente as mesmas versões serão usadas sempre.
Atenção: o
uv.locké gerenciado automaticamente pelo UV e não deve ser editado manualmente.
Como o UV cria o .venv automaticamente ao adicionar a primeira biblioteca
Uma diferença que chama atenção logo no começo é que o UV não cria o ambiente virtual durante o uv init. Ele cria na primeira vez que você executa um comando que precisa dele, como o uv add para instalar uma biblioteca ou o uv run para executar um script.
Por exemplo, ao rodar:
uv add fastapiO UV cria o .venv automaticamente, instala o FastAPI e todas as suas dependências, e atualiza tanto o pyproject.toml quanto o uv.lock em uma única operação.
Depois que o ambiente virtual for criado, verifique se o VS Code está apontando para ele. Olhe no canto inferior direito da tela, onde aparece a versão do Python selecionada. Se não estiver mostrando o interpretador do seu .venv, clique nele e selecione manualmente o ambiente virtual do projeto.
Gerenciamento de Dependências e Sincronização com UV
Com o projeto criado, o dia a dia de trabalho fica bem mais simples. Adicionar, remover e sincronizar dependências são operações rápidas e que não exigem nenhum passo manual além do próprio comando.
Instalando e removendo bibliotecas com uv add e uv remove
Para instalar uma biblioteca, o comando é:
uv add nome-da-bibliotecaE para remover:
uv remove nome-da-bibliotecaO que torna esse processo diferente do pip é que o uv remove não remove apenas a biblioteca solicitada. Ele identifica todas as dependências que aquela biblioteca trouxe e remove todas elas junto, desde que não sejam usadas por outro pacote do projeto. Seu ambiente virtual fica sempre limpo e sem pacotes desnecessários.
Como sincronizar o ambiente virtual com uv sync
Imagine que você editou o pyproject.toml diretamente, removendo algumas bibliotecas e adicionando outras, sem passar pelos comandos uv add e uv remove. Nesse caso, o ambiente virtual ainda está desatualizado em relação ao que você declarou no arquivo.
Para resolver isso, basta rodar:
uv syncO uv sync instala os pacotes que estão faltando e remove os que não são mais necessários, mantendo o ambiente virtual sempre alinhado com o pyproject.toml e o uv.lock.
Esse comando também é útil quando você clona um projeto de outra pessoa e quer garantir que todas as dependências estão instaladas corretamente, nas versões exatas registradas no lockfile.
Detecção de incompatibilidade de pacotes: o exemplo do TensorFlow
Uma funcionalidade que faz bastante diferença no dia a dia é a capacidade do UV de identificar incompatibilidades antes de tentar instalar qualquer coisa. Se você tentar instalar uma biblioteca que não é compatível com a versão do Python configurada no projeto, o UV vai te avisar imediatamente com uma mensagem clara, sem deixar o ambiente em estado inconsistente.
Um exemplo concreto: o TensorFlow tem restrições de compatibilidade com versões mais recentes do Python. Se o seu projeto estiver configurado para usar Python 3.14 e você tentar rodar:
uv add tensorflowO UV vai retornar um erro informando que nenhuma versão do TensorFlow tem wheels compatíveis com aquela versão do Python. Nenhuma instalação parcial, nenhuma bagunça no ambiente. Basta ajustar a versão do Python no pyproject.toml para uma compatível, como a 3.11, e rodar o comando novamente.
Gerenciamento de Versões do Python com UV
Trocar a versão do Python em um projeto costumava ser uma operação cheia de etapas: instalar a versão com o pyenv, recriar o ambiente virtual, reinstalar as dependências. Com o UV, esse processo se resume a duas ações.
Como trocar a versão do Python direto no pyproject.toml
Abra o pyproject.toml e localize a linha requires-python. Mude para a versão desejada:
[project]
requires-python = ">=3.11"Você também pode atualizar o arquivo .python-version, que indica a versão exata em uso:
3.11Depois de salvar os arquivos, basta rodar qualquer comando do UV, como uv add ou uv sync. O UV vai identificar a mudança, baixar a nova versão do Python se necessário, recriar o ambiente virtual e reinstalar todas as dependências automaticamente, mantendo tudo registrado no uv.lock.
Instalando versões específicas com uv python install
Se você quiser instalar uma versão do Python de forma explícita, sem depender da que já está no sistema, o UV também cobre isso:
uv python install 3.11Com um único comando, é possível instalar múltiplas versões do Python e alternar entre elas conforme a necessidade do projeto. Isso elimina a dependência do pyenv para esse tipo de tarefa.
Como Migrar Projetos Existentes para o UV
Se você já tem projetos rodando com pip e requirements.txt, não precisa recomeçar do zero para adotar o UV. A migração é direta e leva poucos minutos.
Usando uv add -r requirements.txt para importar dependências
Abra o terminal na pasta do projeto existente e rode:
uv initEsse comando vai criar os arquivos de configuração do UV sem sobrescrever o código que você já tem. Se existir um main.py no projeto, ele não será substituído. Depois, importe todas as dependências do requirements.txt de uma vez:
uv add -r requirements.txtEsse comando adiciona todas as dependências ao pyproject.toml e atualiza o lockfile automaticamente, replicando o comportamento do pip install -r requirements.txt com o benefício de já deixar tudo integrado à estrutura do UV.
Feito isso, seu projeto já está operando com o UV. Você pode manter o requirements.txt por compatibilidade com outras ferramentas ou simplesmente deixar o UV gerenciar tudo pelo pyproject.toml daqui em diante.
O que muda no seu fluxo de trabalho após a migração
Na prática, a mudança é pequena no dia a dia, mas os benefícios aparecem rápido. Os principais comandos que você vai usar no lugar dos antigos são:
| Antes | Com UV |
|---|---|
pip install pacote | uv add pacote |
pip uninstall pacote | uv remove pacote |
pip freeze > requirements.txt | Automático |
python -m venv .venv | Automático |
pip install -r requirements.txt | uv sync |
python script.py | uv run script.py |
O que muda de verdade é que você para de se preocupar com a manutenção manual das dependências. O UV cuida do pyproject.toml e do uv.lock automaticamente, e você sabe que qualquer pessoa que clonar o projeto e rodar uv sync vai ter exatamente o mesmo ambiente que você tem.
Conclusão
O UV não é só uma ferramenta mais rápida que o pip. Ele representa uma mudança real na forma de trabalhar com projetos Python, eliminando etapas manuais que sempre foram chatas e propensas a erro, como atualizar o requirements.txt, recriar ambientes virtuais na troca de versão ou garantir que as dependências estão iguais em todas as máquinas. Com poucos comandos, você tem tudo isso resolvido de forma automática e confiável.
Se você ainda não adotou o UV, esse é um bom momento para começar. Seja em um projeto novo com uv init, ou migrando algo que já existe com uv add -r requirements.txt, a curva de aprendizado é curta e os ganhos aparecem rápido. Aos poucos, você vai perceber que dificilmente vai querer voltar ao fluxo antigo.
Se você quer acelerar sua jornada com uma estrutura completa, didática testada e suporte sempre que precisar, conheça nosso minicurso gratuito de Python e o Curso Completo de Python.
Além disso, se preferir esse conteúdo no formato de vídeo-aula, assista ao vídeo abaixo ou acesse o nosso canal do YouTube!
O que você aprende neste vídeo
Resposta rápida: O uv é um gerenciador de pacotes, ambientes virtuais e versões do Python num único binário. Depois de instalar, uv init cria o projeto, uv add instala a biblioteca e monta o ambiente virtual sozinho, e o uv.lock guarda a versão exata de cada dependência. Projeto antigo migra com uv add -r requirements.txt.
Neste vídeo (20 min):
- 0:00 - apresenta o uv como gerenciador de pacotes, versões e ambientes virtuais
- 1:45 - instala o uv por
pip install uvou pelo instalador da Astral - 3:35 - roda
uv inite ganha git,main.pyepyproject.toml - 4:40 - compara o
pyproject.tomlcom orequirements.txte opip freeze - 5:50 - usa
uv add fastapi: o ambiente virtual nasce sozinho em segundos - 8:00 - mostra o
uv.locktravando a versão exata de cada dependência - 11:00 - executa o código com
uv run, que resolve dependência faltando - 12:00 - troca a versão do Python editando os dois arquivos do projeto
- 13:30 - vê o uv recusar pacote sem versão compatível com o Python do projeto
- 15:00 - apaga a biblioteca e as dependências dela com
uv remove - 16:10 - alinha o ambiente com
uv syncapós editar as dependências à mão - 18:00 - migra projeto com pip usando
uv add -r requirements.txt
Trechos do vídeo:
- O uv reúne num único binário o que antes exigia pip, ambiente virtual e gerenciador de versões.
- Depois de instalar o uv, reinicie o terminal e o VS Code para a instalação ser reconhecida.
- O
uv.lockgarante que o projeto no seu computador e no servidor usem as mesmas versões. - A cada biblioteca adicionada, o
pyproject.tomlé atualizado sozinho, sempip freeze.
FAQ – Perguntas Frequentes sobre UV Python
1. O UV Python substitui completamente o pip?
Para a maioria dos projetos, sim. O UV cobre tudo que o pip faz e ainda entrega funcionalidades extras, como gerenciamento de ambientes virtuais, lockfile automático e controle de versões do Python. Em alguns casos muito específicos, como integrações legadas ou ambientes corporativos com restrições, o pip ainda pode ser necessário, mas para o uso cotidiano o UV resolve com folga.
2. Preciso desinstalar o pip para usar o UV?
Não. Os dois podem coexistir no mesmo computador sem nenhum conflito. Você pode começar a usar o UV em projetos novos enquanto mantém projetos antigos rodando com pip normalmente. A migração pode ser feita no seu próprio ritmo, projeto a projeto, sem nenhuma pressa.
3. O UV funciona bem com o VS Code?
Sim, mas é preciso um cuidado simples: após criar o ambiente virtual com o UV, verifique se o VS Code está apontando para o interpretador correto. Olhe no canto inferior direito da tela e confirme que a versão do Python selecionada é a do .venv do seu projeto. Se não estiver, clique nela e selecione manualmente o ambiente virtual criado pelo UV.
Hashtag Treinamentos
Para acessar outras publicações de Python, clique aqui!
Posts mais recentes de Python
- Curso Básico de Python: Saia do Zero em 10 Aulas Grátis
Aprenda com o curso básico de Python gratuito da Hashtag: 10 aulas práticas, exercícios e projetos reais para sair do zero em programação. - Agentes RAG com Python: como criar um assistente de IA
Aprenda a criar Agentes RAG com Python do zero: LangChain, FAISS e OpenAI para montar um assistente de IA que responde com base nos seus documentos. - 25 Tipos de Gráficos em Python: Guia Completo com Código
Aprenda a criar os principais tipos de gráficos em Python com Plotly: barras, pizza, mapas e mais, com código pronto para copiar e usar.
Posts mais recentes da Hashtag Treinamentos
- Planilha de Controle de Notas Fiscais no Excel [Grátis]
Baixe a planilha de controle de notas fiscais no Excel grátis: calcule ISS e retenções, veja o que está em aberto e gere a cobrança de cada nota de serviço. - Qual IA usar na empresa: ChatGPT, Claude ou Perplexity?
Qual IA usar na empresa: veja as diferenças entre ChatGPT, Claude e Perplexity e quando cada um rende mais em cada área da sua equipe. - Apostilas Gratuitas em PDF: Excel, Power BI, Python e IA
Baixe apostilas gratuitas em PDF de Excel, Power BI, Python, Claude e agentes de IA, com exercícios e gabarito. Escolha a sua e comece hoje.
