UV Python: o que é, como usar e configurar ambientes virtuais

O que é UV Python?

O UV Python é um novo gerenciador de pacotes e ambientes virtuais para Python, criado pela Astral, a mesma empresa por trás do Ruff e do Rye. Ele foi desenvolvido para resolver problemas que quase todo programador enfrenta: instalações lentas, dependências quebradas e ambientes confusos.

Diferentemente do pip, o UV foi desenvolvido em Rust, o que o torna de 10 a 100 vezes mais rápido para instalar pacotes e configurar projetos. Além da velocidade, ele já vem com tudo o que você precisa para gerenciar ambientes virtuais, dependências e versões do Python. E você faz tudo com um só comando.

Na prática, o UV é o “tudo em um” do ecossistema Python. Com ele, você pode criar, configurar e rodar seu projeto sem precisar alternar entre várias ferramentas.

Principais vantagens do UV

Se você está começando a programar em Python, o UV elimina boa parte da dor de cabeça de configurar ambientes e gerenciar pacotes.

Já para quem é profissional experiente, ele representa ganhos reais de produtividade e confiabilidade, principalmente em projetos grandes.

Confira todas as vantagens dessa ferramenta:

• Instala pacotes e resolve dependências em segundos;
• Gerencia ambientes virtuais automaticamente;
• É compatível com fluxos de trabalho existentes (pip, venv, poetry);
• Segue os padrões modernos de empacotamento Python;
• Garante ambientes reproduzíveis com arquivos de lock;
• Usa memória de forma eficiente, o que é ótimo para projetos grandes.

Leia também:

Aprender Python do zero: o que você precisa saber para começar

UV vs. PIP: qual é a diferença?

O PIP e o virtualenv sempre foram as ferramentas padrão para instalar pacotes e criar ambientes virtuais em Python. Elas funcionam bem, mas o UV chegou para simplificar (e acelerar muito) esse processo.

Isso porque o UV substitui quatro ferramentas em uma única interface. Ele cria o ambiente virtual e instala as dependências no mesmo comando. E faz isso de forma muito mais rápida e eficiente.

Agora, compare o uso dessas duas ferramentas na prática.

Como era antes (PIP + Virtualenv)

# Criar ambiente virtual
python -m venv meu_ambiente
source meu_ambiente/bin/activate  # Linux/Mac
# ou
meu_ambiente\Scripts\activate     # Windows

# Instalar pacotes
pip install requests pandas numpy
pip freeze > requirements.txt

# Criar ambiente virtual
python -m venv meu_ambiente
source meu_ambiente/bin/activate  # Linux/Mac
# ou
meu_ambiente\Scripts\activate     # Windows

# Instalar pacotes
pip install requests pandas numpy
pip freeze > requirements.txt

Como fica com UV

# Tudo em um comando!
uv venv  # Cria e ativa o ambiente
uv add requests pandas numpy
# O requirements.txt é gerado automaticamente

# Tudo em um comando!
uv venv  # Cria e ativa o ambiente
uv add requests pandas numpy
# O requirements.txt é gerado automaticamente

Ou seja, usar Python com UV significa menos comandos, menos complexidade e mais eficiência.

Para que serve UV Python?

O UV é mais do que um simples gerenciador de pacotes. Ele reúne, em uma única ferramenta, tudo o que você precisa para criar, gerenciar e executar projetos Python de forma rápida e organizada. 

Veja a seguir tudo o que você pode fazer com essa ferramenta:

1. Gerenciamento completo de projetos

Com o UV, você cria e organiza um projeto do zero em segundos:

uv init meu_projeto
cd meu_projeto

uv init meu_projeto
cd meu_projeto

Com esse comando, ele gera automaticamente a estrutura do projeto e o ambiente virtual. Depois, você só precisa adicionar suas dependências:

uv add ruff

uv add ruff

Em poucos milissegundos, o UV:

• Cria o ambiente virtual;
• Resolve as dependências;
• Instala os pacotes necessários.

E, se quiser rodar uma ferramenta direto do ambiente, use:

uv run ruff check

uv run ruff check

Ou seja, você não precisa alternar entre pip, venv e outros comandos: o UV faz tudo de uma vez, de forma integrada e rápida.

2. Execução de scripts isolados

Quer rodar um script simples sem criar um projeto inteiro? O UV também faz isso.

echo 'import requests; print(requests.get("https://astral.sh"))' > exemplo.py
uv add --script exemplo.py requests
uv run exemplo.py

echo 'import requests; print(requests.get("https://astral.sh"))' > exemplo.py
uv add --script exemplo.py requests
uv run exemplo.py

Ele cria automaticamente um ambiente virtual temporário, instala as dependências declaradas e executa o script com segurança. 

3. Instalação e execução de ferramentas CLI

O UV também instala e executa ferramentas de linha de comando (como black, ruff ou pytest) bem mais rápido.

Para executar uma ferramenta sem instalá-la, você pode usar o seguinte comando:

uvx pycowsay "hello world!"

uvx pycowsay "hello world!"

E para instalá-la de forma permanente, use este:

uv tool install ruff
ruff --version

uv tool install ruff
ruff --version

Você ganha tempo e evita conflitos de versão entre ferramentas no seu sistema.

Leia também:

Hello World: guia completo para iniciantes em programação

4. Gerenciamento de versões do Python

O UV permite instalar e gerenciar múltiplas versões do Python, algo que normalmente exige ferramentas extras, como o pyenv.

Você pode instalar várias versões de uma vez com o seguinte comando:

uv python install 3.10 3.11 3.12

uv python install 3.10 3.11 3.12

E criar um ambiente com uma versão específica com este:

uv venv --python 3.12.0

uv venv --python 3.12.0

Ou fixar a versão usada no projeto:

uv python pin 3.11

uv python pin 3.11

Assim, você consegue testar seu código em diferentes versões e manter cada projeto independente e organizado.

5. Interface compatível com o PIP

Se você já usa o PIP, vai se sentir em casa. Isso porque o UV replica os comandos mais comuns da ferramenta, só que muito mais rápido.

Você pode criar um ambiente virtual com o seguinte comando:

uv venv

uv venv

E compilar e sincronizar dependências assim:

uv pip compile requirements.in --output-file requirements.txt
uv pip sync requirements.txt

uv pip compile requirements.in --output-file requirements.txt
uv pip sync requirements.txt

Dessa forma, você pode migrar para o UV sem mudar seu fluxo de trabalho. Afinal, ele entende seus requirements.txt e entrega os mesmos resultados, só que em menos tempo e com menor consumo de memória.

Como instalar o UV Python?

A instalação do UV é supersimples. Em poucos minutos, você já vai sentir a diferença no seu fluxo de trabalho. 

Instalação no Ubuntu e no Linux

Primeiro, abra o terminal e execute o seguinte comando:

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

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

Se preferir, instale globalmente com este código:

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

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

Agora, verifique se deu certo:

uv --version

uv --version

Se aparecer o número da versão, está tudo ok.

Leia também:

Linux na Prática: S.O. mais Utilizado no Mercado

Instalação no Windows

Nesse caso, você precisa executar o seguinte comando no PowerShell (com permissão de administrador):

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

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

Após a instalação, teste com:

uv --version

uv --version

Lembrando que o UV se atualiza sozinho quando há novas versões. Você só precisa rodar o comando abaixo de tempos em tempos:

uv self update

uv self update

Instalação no macOS (opcional)

Para instalar o UV no macOS, você pode usar o mesmo comando do Linux:

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

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

Ou, se preferir, use o Homebrew:

brew install uv

brew install uv

Outras opções de instalação

Se você preferir, pode instalar o UV diretamente do PyPI. Porém, esse método é mais indicado se você já tem um ambiente Python configurado:

Para fazer a instalação, execute:

pip install uv

pip install uv

Ou use este comando:

pipx install uv

pipx install uv

Verificando a instalação

Por fim, você precisa verificar se a instalação deu certo. Para isso, depois que tudo estiver pronto, execute:

uv --help

uv --help

Esse comando mostra todos os subcomandos e opções disponíveis. Lembrando que você pode aprender mais sobre esses processos na documentação oficial do UV Python.

Leia também:

Miniconda: a ferramenta ideal para configurar ambientes Python

Como criar e ativar um ambiente virtual Python com UV: passo a passo

1. Crie um novo projeto Python

No terminal, execute:

uv init explore-uv

uv init explore-uv

O UV vai gerar uma estrutura completa de projeto assim:

.
├── .gitignore
├── .python-version
├── README.md
├── hello.py
└── pyproject.toml

.
├── .gitignore
├── .python-version
├── README.md
├── hello.py
└── pyproject.toml

Ele também inicializa um repositório Git e cria um arquivo hello.py pronto para testar. Em vez de configurar tudo manualmente, o UV já prepara o ambiente ideal para você começar a programar de imediato.

2. Adicione pacotes ao ambiente

No UV, criar o ambiente e instalar pacotes acontece no mesmo comando. Por exemplo, para adicionar o Scikit-learn e o XGBoost, execute:

uv add scikit-learn xgboost

uv add scikit-learn xgboost

Na primeira execução, o UV:

• Cria automaticamente o ambiente virtual .venv;
• Baixa as dependências necessárias;
• Instala tudo de forma otimizada.

Nas próximas vezes, ele reutiliza o mesmo ambiente, atualizando apenas o que for novo. Isso elimina erros de configuração e acelera o setup do projeto, o que é ótimo para quem quer focar no código, não em ajustes de ambiente.

3. Atualize e remova pacotes

Para atualizar dependências, use o seguinte comando.

uv lock
uv sync

uv lock
uv sync

Esses comandos garantem que tudo fique sincronizado e reproduzível.

Já para remover um pacote, execute:

uv remove scikit-learn

uv remove scikit-learn

Assim, o UV desinstala o pacote e atualiza automaticamente o pyproject.toml e o uv.lock, mantendo o ambiente 100% rastreável e versionado.

4. Execute seus scripts Python

Depois de criar o projeto e instalar os pacotes, o próximo passo é rodar o código:

uv run hello.py

uv run hello.py

O comando uv run executa o script dentro do ambiente virtual, sem que você precise ativar manualmente com source .venv/bin/activate. Assim, você mantém tudo isolado, limpo e organizado, sem interferir no Python do seu sistema.

Faça o curso:

Criando seu Setup para Programação Python

Exemplos práticos de Python com UV por sistema

O UV funciona da mesma forma em qualquer sistema operacional. Porém, o processo de instalação e a ativação do ambiente virtual mudam um pouquinho em cada um.

Veja como isso funciona no Ubuntu (Linux), Windows e VS Code:

No Ubuntu e Linux

1. Instale o UV

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

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

Conforme explicado, esse comando baixa o instalador oficial da Astral e adiciona o executável uv ao sistema. Se o Python ainda não estiver instalado, o UV baixa automaticamente a versão mais recente.

2. Crie um novo projeto

uv init projeto-linux

uv init projeto-linux

Esse comando cria uma pasta chamada projeto-linux com:

• Um ambiente virtual (.venv);
• O arquivo pyproject.toml (que lista as dependências);
• Um README.md para começar o projeto.

3. Adicione dependências

uv add requests pandas

uv add requests pandas

Com esse comando, o UV baixa e instala os pacotes dentro do ambiente virtual, mantendo o Python do sistema intocado.

4. Execute o código

uv run main.py

uv run main.py

Assim, o UV garante que o script rode dentro do ambiente virtual. Ele ainda usa um cache global para acelerar futuras instalações, reduzindo o tempo de espera e evitando conflitos de dependência.

1. Instale o UV

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

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

Esse comando baixa e executa o instalador no PowerShell, adicionando o UV ao seu PATH para que possa ser usado em qualquer pasta.

2. Crie e configure o projeto

uv init projeto-windows
cd projeto-windows
uv add requests pandas

uv init projeto-windows
cd projeto-windows
uv add requests pandas

Assim, o UV cria automaticamente o ambiente virtual (.venv\Scripts\python.exe) e instala os pacotes dentro dele.

Se quiser ativar manualmente, execute:

.venv\Scripts\activate

.venv\Scripts\activate

3. Rode seu script

uv run main.py

uv run main.py

Dessa forma, o UV executa o código dentro do ambiente correto, usando a versão adequada do Python. Vale lembrar que o PowerShell cria um diretório .uv dentro do seu perfil de usuário, onde o UV gerencia versões do Python e ambientes, economizando espaço e tempo nas próximas instalações.

No VS Code

1. Abra o projeto criado com o UV

O VS Code detecta automaticamente o ambiente virtual .venv dentro da pasta.

2. Selecione o interpretador do UV

• Pressione Ctrl + Shift + P;
• Busque por “Python: Select Interpreter”;
• Escolha o ambiente localizado em:
  • .venv/bin/python (Linux/macOS);
  • .venv\Scripts\python.exe (Windows).

3. Execute seu código direto no editor

Agora, crie o arquivo main.py e clique em “Run Python File” ou pressione F5.

Dessa forma, o VS Code passa a usar o Python do ambiente virtual do UV, garantindo que todas as dependências do projeto sejam reconhecidas pelo IntelliSense, autocompletar e depurador.

Assim, tudo que você instalar com uv add já fica disponível automaticamente no editor, sem precisar reconfigurar nada.

Como gerenciar pacotes Python com UV

O UV simplifica o gerenciamento de pacotes e ambientes em Python, substituindo vários comandos do pip e venv por uma experiência integrada, rápida e previsível. Entenda como a seguir:

Instale pacotes específicos do projeto

Para projetos gerenciados pelo UV, prefira usar:

uv add requests pandas

uv add requests pandas

Esse comando:

• Cria (ou reutiliza) o ambiente .venv;
• Atualiza automaticamente o pyproject.toml;
• Gera ou atualiza o uv.lock.

Se você quiser manter a compatibilidade com requirements.txt, pode usar a interface pip-compatível do UV:

uv pip install requests pandas

uv pip install requests pandas

Ele é ideal para projetos que ainda seguem o formato tradicional do pip.

Liste pacotes e versões instaladas

Use os subcomandos compatíveis com o pip para inspecionar seu ambiente:

# Lista pacotes e versões instaladas
uv pip list

# Gera o arquivo requirements.txt
uv pip freeze

# Mostra detalhes de um pacote específico
uv pip show requests

# Exibe a árvore de dependências (explícitas e transitivas)
uv pip tree

# Lista pacotes e versões instaladas
uv pip list

# Gera o arquivo requirements.txt
uv pip freeze

# Mostra detalhes de um pacote específico
uv pip show requests

# Exibe a árvore de dependências (explícitas e transitivas)
uv pip tree

Esses comandos funcionam dentro da pasta do projeto, sendo que o UV identifica automaticamente qual .venv utilizar. Por isso, eles são ideais para auditorias rápidas e conferência de versões.

Garanta compatibilidade entre pacotes e projetos

Aqui está uma das maiores vantagens do UV: ele garante ambientes idênticos em qualquer máquina. O arquivo uv.lock é o coração desse processo. Sempre que você executa uv add ou uv sync, o UV registra:

• As versões exatas de cada pacote;
• Suas dependências transitivas;
• Hashes de verificação de integridade.

Para replicar o ambiente em outra máquina, você só precisa rodar:

uv sync

uv sync

Assim, você recria o mesmo ambiente em outra máquina. Vale lembrar que, quando há conflito de versões, o UV mostra mensagens claras, indicando exatamente quais pacotes causaram o problema, o que facilita muito a correção.

Como aprender Python, criar ambientes isolados e gerenciar pacotes com UV Python

O UV Python marca uma nova geração de ferramentas para quem desenvolve em Python, mais rápido, simples e confiável. Com ele, você cria ambientes virtuais, instala pacotes e mantém seus projetos organizados em poucos comandos.

Mas, para dominar essa ferramenta, antes de tudo, você precisa entender bem como o Python funciona, sua lógica e boas práticas de código.

E a melhor forma de aprender tudo isso do zero é fazer o curso gratuito Python para iniciantes, da Asimov Academy. Nele, você vai aprender Python de forma prática e simples, mesmo que nunca tenha programado antes. 

No final do curso, você terá desenvolvido seu primeiro aplicativo com Python e ficará pronto para começar novos projetos com essa linguagem.

Inscreva-se agora e comece a mudar o seu futuro!

Curso Gratuito

Seu primeiro projeto Python – curso grátis com certificado!

Vá do zero ao primeiro projeto em apenas 2 horas com o curso Python para Iniciantes.

Comece agora