Python UV: O guia definitivo para o gerenciador de pacotes Python mais rápido

O que é o Python UV?

O UV é um gerenciador e instalador de pacotes Python moderno e de alto desempenho, escrito em Rust. Ele serve como um substituto para as ferramentas tradicionais de gerenciamento de pacotes Python, como o pip, oferecendo melhorias significativas em velocidade, confiabilidade e resolução de dependências.

Essa ferramenta representa uma nova geração de gerenciadores de pacotes Python, projetada para abordar pontos problemáticos comuns no ecossistema Python, como tempos de instalação lentos, conflitos de dependência e complexidade de gerenciamento de ambiente. O UV consegue isso por meio de sua arquitetura inovadora e implementação eficiente, tornando-o de 10 a 100 vezes mais rápido do que os gerenciadores de pacotes tradicionais.

Principais recursos que fazem o UV se destacar:

• Instalação de pacotes e resolução de dependências extremamente rápidas
• Compatível com ferramentas e fluxos de trabalho Python existentes
• Gerenciamento de ambiente virtual integrado
• Suporte a padrões modernos de embalagem
• Bloqueio de dependência confiável e ambientes reproduzíveis
• Operação com eficiência de memória, especialmente para grandes projetos

Seja trabalhando em pequenos projetos pessoais ou gerenciando aplicativos Python de grande escala, o UV oferece uma solução robusta e eficiente para o gerenciamento de pacotes. Neste tutorial, abordaremos todos os aspectos essenciais do UV para que você possa começar a usá-lo imediatamente.

A diferença entre UV, Poetry, PIP, Conda e virtualenv

A primeira pergunta que os desenvolvedores costumam fazer antes de mudar para uma nova ferramenta é: "Como ela se compara à que eu já estou usando?". Na área de gerenciamento de projetos e dependência de Python, essas quatro ferramentas já são as mais comuns:

• PIP
• Poesia
• Conda
• virtualenv

Vamos comparar o UV com cada uma dessas ferramentas para ajudar você a decidir se o UV é a escolha certa para suas necessidades, antes de entrar nos detalhes.

UV vs. PIP e virtualenv

O PIP e o virtualenv têm sido as ferramentas tradicionais para o gerenciamento de pacotes Python e a criação de ambientes virtuais. Embora eles façam o trabalho, o UV oferece várias vantagens atraentes:

• Velocidade: A implementação do Rust do UV o torna significativamente mais rápido do que o PIP para a instalação de pacotes e a resolução de dependências, muitas vezes concluindo tarefas em segundos que levariam minutos para o PIP.
• Gerenciamento ambiental integrado: Enquanto o virtualenv lida apenas com a criação de ambientes e o PIP lida apenas com o gerenciamento de pacotes, o UV combina as duas funcionalidades em uma única ferramenta, simplificando o fluxo de trabalho.

O UV mantém total compatibilidade com o ecossistema do PIP e, ao mesmo tempo, aborda suas principais limitações. Ele pode usar os mesmos arquivos requirements.txt e índices de pacotes, o que torna a migração perfeita. As principais diferenças são:

• Desempenho: Os downloads paralelos do UV e a resolução otimizada de dependências o tornam de 10 a 100 vezes mais rápido do que o PIP para projetos grandes.
• Uso da memória: O UV usa muito menos memória do que o PIP durante a instalação de pacotes e a resolução de dependências.
• Tratamento de erros: O UV fornece mensagens de erro mais claras e melhor resolução de conflitos quando as dependências se chocam.
• Reprodutibilidade: A abordagem de arquivo de bloqueio do UV garante ambientes consistentes em sistemas diferentes, algo que não é garantido com arquivos requirements.txt básicos.

Embora o PIP e o virtualenv continuem sendo opções viáveis, a arquitetura moderna e a funcionalidade combinada do UV o tornam uma alternativa atraente para os desenvolvedores que buscam melhor desempenho e um fluxo de trabalho mais simplificado. A capacidade de inserir o UV em projetos existentes sem interromper os processos estabelecidos torna-o particularmente atraente para as equipes que desejam modernizar gradualmente o conjunto de ferramentas de desenvolvimento em Python.

UV vs. Conda

As pessoas que não usam PIP e virtualenv geralmente recorrem ao Conda e têm bons motivos para isso:

• O Conda oferece uma solução completa de gerenciamento de pacotes que lida não apenas com os pacotes Python, mas também com as dependências em nível de sistema
• Ele se destaca no gerenciamento de ambientes complexos de computação científica com pacotes como NumPy, SciPy e TensorFlow
• Os ambientes Conda são mais isolados e reproduzíveis em diferentes sistemas operacionais
• Ele tem suporte integrado para diferentes versões do Python e pode alternar entre elas facilmente
• A distribuição do Anaconda vem com muitos pacotes científicos pré-instalados, o que a torna conveniente para cientistas de dados

No entanto, mesmo os usuários mais dedicados do Conda devem considerar a mudança para o UV por vários motivos. A instalação ultrarrápida de pacotes e a resolução de dependências do UV podem acelerar drasticamente a configuração do ambiente em comparação com o desempenho às vezes lento do Conda. Seu consumo mínimo de recursos significa menos uso de memória e inicializações mais rápidas. O UV também se integra perfeitamente aos padrões e ferramentas de empacotamento Python existentes, facilitando o trabalho com o ecossistema Python mais amplo. Para projetos que não requerem o gerenciamento de pacotes não-Python do Conda, o UV oferece uma solução mais simplificada e eficiente que pode melhorar significativamente os fluxos de trabalho de desenvolvimento.

UV vs. Poetry

Fui usuário do Conda por quase três anos, mas depois de experimentar o Poetry algumas vezes, nunca mais toquei no Conda com velocidade de tartaruga. Justamente quando eu estava me sentindo confortável com a poesia, encontrei o UV e ele parece prometer quase as mesmas coisas que a poesia:

• Gerenciamento de dependências: Ambas as ferramentas lidam com dependências de pacotes e ambientes virtuais de forma eficaz
• Estrutura do projeto: Ambos fornecem ferramentas para inicialização e estruturação de projetos Python
• Bloquear arquivos: Ambos geram arquivos de bloqueio para garantir ambientes reproduzíveis
• Publicação do pacote: Ambos suportam a publicação de pacotes no PyPI
• Ferramentas modernas: Ambos representam abordagens modernas para o gerenciamento de projetos Python

No entanto, a característica que define o UV é sua velocidade extremamente rápida e o uso mínimo de recursos. Embora o Poetry seja uma melhoria significativa em relação às ferramentas tradicionais, o UV leva o desempenho a outro nível devido à sua implementação do Rust. Além disso, a compatibilidade do UV com o pacote Python existente significa que ele pode funcionar junto com outras ferramentas, como pip, oferecendo flexibilidade que a abordagem mais opinativa do Poetry às vezes não oferece.

Aqui está uma tabela que resume as diferenças que acabamos de abordar: 

Se você acha que vale a pena trocar o UV, continue lendo.

Primeiros passos com projetos UV para Python

Nesta seção, abordaremos como iniciar um projeto do zero usando o UV. Discutiremos como migrar de projetos existentes para o UV em uma seção posterior.

Instalação de UV

O UV pode ser instalado em todo o sistema usando o cURL no macOS e no Linux:

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

E com o Powershell no Windows (certifique-se de que você execute o Powershell com privilégios de administrador):

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

O UV também está disponível via Homebrew:

$ brew install uv

Uma instalação PIP é compatível, mas não é recomendada:

$ pip install uv  # Make sure you have a virtual environment activated

Depois disso, você pode verificar a instalação executando uv version:

$ uv version
uv 0.4.25 (97eb6ab4a 2024-10-21)

Inicialização de um novo projeto

Trabalhar em projetos é a parte principal da experiência na UV. Você começa inicializando um projeto vazio usando o comando uv init:

$ uv init explore-uv
Initialized project explore-uv at /Users/bexgboost/projects/explore-uv

O comando criará imediatamente um novo diretório explore-uv com o seguinte conteúdo:

$ cd explore-uv
$ tree -a
.
├── .gitignore
├── .python-version
├── README.md
├── hello.py
└── pyproject.toml

O Git é inicializado automaticamente e os principais arquivos relacionados ao git, como .gitignore e um README.md vazio, são gerados. O arquivo .python-version contém a versão do Python usada no projeto, enquanto o pyproject.toml serve como o principal arquivo de configuração para metadados e dependências do projeto. Um arquivo de amostra hello.py também é criado para ajudar você a começar rapidamente.

Você pode saber mais sobre a criação de projetos na documentação do UV.

Adição de dependências iniciais ao projeto

O UV combina a criação do ambiente e a instalação da dependência em um único comando: uv add:

$ uv add scikit-learn xgboost
Using CPython 3.9.20 interpreter at: /opt/homebrew/opt/python@3.9/bin/python3.9
Creating virtual environment at: .venv
Resolved 6 packages in 1.78s
⠧ Preparing packages... (2/5)
Prepared 5 packages in 1m 23s
Installed 5 packages in 45ms
 + joblib==1.4.2
 + numpy==2.0.2
 + scikit-learn==1.5.2
 ...

Na primeira vez que você executa o comando add, o UV cria um novo ambiente virtual no diretório de trabalho atual e instala as dependências especificadas. Nas execuções subsequentes, o UV reutilizará o ambiente virtual existente e instalará ou atualizará apenas os pacotes recém-solicitados, garantindo um gerenciamento eficiente das dependências.

Outro processo importante que ocorre em cada comando do add é a resolução de dependências. O UV usa um moderno resolvedor de dependências que analisa todo o gráfico de dependências para encontrar um conjunto compatível de versões de pacotes que satisfaçam todos os requisitos. Isso ajuda a evitar conflitos de versão e garante ambientes reproduzíveis. O resolvedor considera fatores como restrições de versão, compatibilidade da versão do Python e requisitos específicos da plataforma para determinar o conjunto ideal de pacotes a serem instalados.

O UV também atualiza os arquivos pyproject.toml e uv.lock após cada comando add. Aqui está a aparência do arquivo TOML após a instalação do Scikit-learn e do XGBoost:

$ cat pyproject.toml
[project]
name = "explore-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "scikit-learn>=1.5.2",
    "xgboost>=2.0.3",
]

Para remover uma dependência do ambiente e do arquivo pyproject.toml, você pode usar o comando uv remove. Ele desinstalará o pacote e todas as suas dependências-filhas:

$ uv remove scikit-learn

Discutiremos o gerenciamento de dependências em mais detalhes em uma seção posterior.

Execução de scripts Python com UV

Depois de instalar as dependências necessárias, você pode começar a trabalhar em seus scripts Python normalmente. O UV oferece algumas maneiras diferentes de executar o código Python:

Para executar um script Python diretamente, você pode usar o comando uv run seguido pelo nome do script em vez da sintaxe usual python script.py:

$ uv run hello.py

O comando run garante que o script seja executado dentro do ambiente virtual UV criado para o projeto. 

Gerenciando versões do Python no UV

O gerenciamento das versões do Python é uma parte fundamental do gerenciamento de dependências. O UV fornece comandos simples para controlar qual versão do Python você usa. Vamos explorar como você pode usar o comando uv python.

Listando as versões existentes do Python

Como é comum que os sistemas já tenham o Python instalado, o UV pode descobrir essas instalações existentes por padrão. Por exemplo, para listar todas as versões do Python que o UV detecta em seu sistema, execute o seguinte comando:

$ uv python list --only-installed
cpython-3.13.0-macos-aarch64-none     /opt/homebrew/opt/python@3.13/bin/python3.13 -> ../Frameworks/Python.framework/Versions/3.13/bin/python3.13
cpython-3.12.7-macos-aarch64-none     /opt/homebrew/opt/python@3.12/bin/python3.12 -> ../Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.5-macos-aarch64-none     /Users/bexgboost/miniforge3/bin/python3.12
cpython-3.12.5-macos-aarch64-none     /Users/bexgboost/miniforge3/bin/python3 -> python3.12
cpython-3.12.5-macos-aarch64-none     /Users/bexgboost/miniforge3/bin/python -> python3.12
cpython-3.11.10-macos-aarch64-none    /opt/homebrew/opt/python@3.11/bin/python3.11 -> ../Frameworks/Python.framework/Versions/3.11/bin/python3.11
cpython-3.11.7-macos-aarch64-none     /Users/bexgboost/.local/share/uv/python/cpython-3.11.7-macos-aarch64-none/bin/python3 -> python3.11
cpython-3.10.15-macos-aarch64-none    /opt/homebrew/opt/python@3.10/bin/python3.10 -> ../Frameworks/Python.framework/Versions/3.10/bin/python3.10
cpython-3.9.20-macos-aarch64-none     /opt/homebrew/opt/python@3.9/bin/python3.9 -> ../Frameworks/Python.framework/Versions/3.9/bin/python3.9
cpython-3.9.6-macos-aarch64-none      /Library/Developer/CommandLineTools/usr/bin/python3 -> ../../Library/Frameworks/Python3.framework/Versions/3.9/bin/python3

O comando detectou corretamente minhas versões do Python instaladas no Conda e no Brew.

Alterar as versões do Python para o projeto atual 

Você pode trocar as versões do Python para o seu projeto UV atual a qualquer momento, desde que a nova versão atenda às especificações do arquivo pyproject.toml. Por exemplo, o arquivo a seguir requer as versões 3.9 e superiores do Python:

...
requires-python = ">=3.9"

Isso significa que você pode alterar a versão do Python no arquivo .python-version para qualquer versão acima, como 3.11.7. Depois disso, ligue para uv sync.

O comando primeiro verifica as instalações existentes do Python. Se a versão solicitada não for encontrada, o UV fará o download e a instalará dentro do caminho /Users/username/.local/share/uv/python. O UV também cria um novo ambiente virtual dentro do diretório do projeto, substituindo o antigo. 

Esse novo ambiente não tem as dependências listadas no arquivo pyproject.toml, portanto, você precisa instalá-las com o seguinte comando:

$ uv pip install -e .

Observe que, às vezes, os comandos uv podem gerar erros Permission Denied. Nesses casos, certifique-se de usar o comando sudo se você estiver no macOS ou Linux ou execute o prompt de comando com privilégios de administrador se estiver no Windows. Uma solução ainda melhor seria alterar a propriedade do diretório inicial do UV para o usuário:

$ sudo chown -R $USER ~/.local/share/uv  # macOS or Linux

Para saber mais sobre o gerenciamento de versões do Python com o UV, consulte a documentação. 

O que são ferramentas UV e como usá-las?

Alguns pacotes Python são expostos como ferramentas de linha de comando, como black para formatação de código, flake8 para linting, pytest para teste, mypy para verificação de tipo etc. O UV fornece duas interfaces especiais para gerenciar esses pacotes:

1. Usando o site uv tool run:

$ uv tool run black hello.py

2. Usando o comando mais curto e mais conveniente uvx:

$ uvx black hello.py

Quando esses comandos são executados, o UV cria um ambiente virtual temporário em seu cache. A ferramenta solicitada é instalada e executada a partir daí. Em outras palavras, você pode usar ferramentas de linha de comando sem instalá-las no ambiente virtual do projeto, o que resulta em uma execução mais rápida e dependências de projeto mais limpas.

Pontos principais sobre as interfaces de execução da ferramenta:

• Funciona com qualquer pacote Python que forneça ferramentas de linha de comando, como flake8, mypy, black ou pytest
• Os ambientes armazenados em cache são limpos automaticamente quando você limpa o cache do UV
• Novos ambientes em cache são criados sob demanda quando necessário
• Perfeito para o uso ocasional de ferramentas de desenvolvimento

Leia a seção UV Tools da documentação para saber mais sobre essas interfaces.

O que são arquivos de bloqueio no UV?

Os arquivos de bloqueio (uv.lock) são uma parte essencial do gerenciamento de dependências no UV. Quando você executa comandos uv add para instalar dependências, o UV gera e atualiza automaticamente um arquivo uv.lock. Esse arquivo de bloqueio tem várias finalidades importantes:

• Ele registra as versões exatas de todas as dependências e suas subdependências que foram instaladas.
• Ele garante compilações reproduzíveis ao "bloquear" as versões de dependência em diferentes ambientes.
• Isso ajuda a evitar o "inferno das dependências", mantendo versões consistentes dos pacotes.
• Isso acelera as instalações, pois o UV pode usar as versões bloqueadas em vez de resolver as dependências novamente.

O UV gerencia o arquivo de bloqueio automaticamente - você não precisa editá-lo manualmente. O arquivo de bloqueio deve ser confirmado no controle de versão para garantir que todos os desenvolvedores usem as mesmas versões de dependência.

A diferença entre Lock Files e requirements.txt

Embora os arquivos de bloqueio e o site requirements.txt sirvam para rastrear dependências, eles têm finalidades e casos de uso distintos. Os arquivos de bloqueio contêm informações detalhadas sobre as versões exatas dos pacotes e sua árvore de dependência completa, garantindo ambientes consistentes em todo o desenvolvimento. Os arquivos Requirements.txt são mais simples, geralmente listando apenas as dependências diretas, e são amplamente suportados pelas ferramentas Python.

Os arquivos de bloqueio são essenciais para o desenvolvimento, a fim de manter compilações reproduzíveis e evitar conflitos de dependência. Os arquivos Requirements.txt são mais adequados para cenários de implementação ou para compartilhar código com usuários que talvez não usem o UV. Eles também são necessários para a compatibilidade com ferramentas e serviços que não suportam o formato de arquivo de bloqueio do UV.

Você pode manter os dois arquivos usando o arquivo de bloqueio do UV para desenvolvimento e gerando um requirements.txt para implantação. Para gerar um requirements.txt a partir de um arquivo de bloqueio UV, use o seguinte comando:

$ uv export -o requirements.txt

Isso cria o arquivo de texto com versões fixadas com base no seu arquivo de bloqueio, facilitando o compartilhamento das dependências do seu projeto em um formato padrão e, ao mesmo tempo, beneficiando-se do gerenciamento avançado de dependências do UV durante o desenvolvimento.

Você pode saber mais sobre o gerenciamento de arquivos de bloqueio na documentação. 

Gerenciamento avançado de dependências com UV

Nesta seção, exploraremos métodos mais sofisticados para gerenciar dependências no UV. Aprenderemos como atualizar dependências, torná-las opcionais ou torná-las parte de um grupo de dependências.

Atualização de dependências

Em projetos de longo prazo, é comum atualizar os pacotes que você está usando para trazer os recursos mais recentes para a mesa. Ou, às vezes, um pacote que você está usando introduz alterações significativas e você quer garantir que essa versão não seja instalada acidentalmente em seu ambiente. O comando add pode ser usado novamente nesses e em qualquer outro cenário em que você precise alterar as restrições ou versões das dependências existentes.

1. Instalar a versão mais recente de um pacote:

$ uv add requests

2. Instalação de uma versão específica:

$ uv add requests=2.1.2

3. Altera os limites das restrições de um pacote:

$ uv add 'requests<3.0.0'

4. Tornar uma dependência específica da plataforma:

$ uv add 'requests; sys_platform="linux"' 

Adição de dependências opcionais

Dependências opcionais são pacotes que não são necessários para a funcionalidade principal do seu projeto, mas podem ser necessários para recursos específicos. Por exemplo, o Pandas tem um extra excel e um extra plot para evitar a instalação dos analisadores do Excel e do matplotlib, a menos que alguém os exija explicitamente. Os opcionais geralmente são instalados com a sintaxe pip install pandas[plot, excel]. 

Com o UV, essa sintaxe é um pouco diferente. Primeiro, verifique se o pacote principal do Pandas está instalado:

$ uv add pandas

Em seguida, adicione suas dependências opcionais:

$ uv add pandas --optional plot excel

Depois de resolvidos, eles serão listados em seu site pyproject.toml com o seguinte formato:

[project]
name = "explore-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "pandas>=2.2.3",
    "requests>=2.32.3",
]
[project.optional-dependencies]
plot = [
    "excel>=1.0.1",
    ...
]

Grupos de dependência

Os grupos de dependências permitem que você organize suas dependências em grupos lógicos, como dependências de desenvolvimento, dependências de teste ou dependências de documentação. Isso é útil para manter as dependências de produção separadas das dependências de desenvolvimento.

Para adicionar uma dependência a um grupo específico, use o sinalizador --group:

$ uv add --group group_name package_name

Em seguida, os usuários poderão controlar quais grupos serão instalados usando as tags --group, --only-group e --no-group.

Mudança de PIP e Virtualenv para UV

A migração do PIP e do virtualenv para o UV é simples, pois o UV mantém a compatibilidade com os padrões de empacotamento do Python existentes. Aqui está um guia passo a passo para que você faça a transição sem problemas:

1. Conversão de um projeto virtualenv existente

Se você já tiver um projeto usando virtualenv e pip, comece gerando um arquivo requirements.txt a partir do seu ambiente atual, caso ainda não o tenha feito:

$ pip freeze > requirements.txt

Em seguida, crie um novo projeto UV no mesmo diretório:

$ uv init .

Por fim, instale as dependências do seu arquivo de requisitos:

$ uv pip install -r requirements.txt

2. Substituição de comandos comuns do pip/virtualenv

Aqui você encontra uma referência rápida para substituir comandos comuns do pip e do virtualenv por seus equivalentes em UV:

Após a migração, você pode remover com segurança o diretório virtualenv antigo e começar a usar o gerenciamento de ambiente virtual do UV. A transição é normalmente perfeita e você sempre pode voltar aos comandos pip por meio da camada de compatibilidade pip do UV, se necessário.

Conclusão

O UV representa um avanço significativo no gerenciamento de pacotes Python, oferecendo uma alternativa moderna, rápida e eficiente às ferramentas tradicionais. Suas principais vantagens incluem:

• Desempenho extremamente rápido com aprimoramentos de velocidade de 10 a 100 vezes em relação ao pip
• Integração perfeita com os padrões de empacotamento Python existentes
• Gerenciamento de ambiente virtual integrado
• Resolução eficiente de dependências e suporte a arquivos de bloqueio
• Baixo consumo de memória e de recursos

Quer você esteja iniciando um novo projeto ou migrando um projeto existente, o UV oferece uma solução robusta que pode melhorar significativamente o seu fluxo de trabalho de desenvolvimento em Python. Sua compatibilidade com as ferramentas existentes faz com que seja uma escolha fácil para os desenvolvedores que desejam modernizar sua cadeia de ferramentas sem interromper seus processos atuais.

À medida que o ecossistema Python continua a evoluir, ferramentas como o UV demonstram como tecnologias modernas, como o Rust, podem aprimorar a experiência de desenvolvimento, mantendo a simplicidade e a acessibilidade que os desenvolvedores Python valorizam.

Se você quiser saber mais sobre o gerenciamento de dependências ou sobre o Python em geral, consulte estas fontes adicionais:

• Tutorial de Python para iniciantes
• Tutorial do PIP Python: Guia definitivo
• Curso de desenvolvimento de pacotes Python
• As 9 principais alternativas ao Anaconda para o gerenciamento do ambiente Python
• Cientista de dados em Python | Aprenda Python para ciência de dados
• Poesia Python: Ambiente Python moderno e eficiente e gerenciamento de dependências