uv - Novo Gerenciador de Pacotes, Projetos e Ambientes do Python

Boas coisas sobre o Python uv

Conteúdo da página

Python uv (pronunciado “you-vee”) é um moderno e de alto desempenho gerenciador de pacotes e projetos Python escrito em Rust. Foi projetado como uma substituição direta para ferramentas tradicionais de gerenciamento de pacotes Python, como pip, pip-tools, virtualenv, pipx e pyenv, visando simplificar e acelerar os fluxos de trabalho de desenvolvimento Python.

O uv é desenvolvido pela Astral, a equipe por trás do popular linter Python Ruff, e foi projetado para abordar pontos problemáticos comuns no ecossistema Python — como instalações lentas, conflitos de dependências e gerenciamento complexo de ambientes — aproveitando o desempenho do Rust e a arquitetura moderna de software.

uv python ultra-violet spa

Principais Funcionalidades do uv

  • Velocidade Excepcional: O uv é significativamente mais rápido do que as ferramentas tradicionais — normalmente 8–10x mais rápido do que o pip sem cache, e até 80–115x mais rápido com um cache quente.
  • Ferramenta Completa: Combina a instalação de pacotes, resolução de dependências, gerenciamento de ambientes virtuais, gerenciamento de versões do Python, scaffolding de projetos e execução de scripts em uma única ferramenta.
  • Compatibilidade: Oferece uma interface de linha de comando compatível com o pip, tornando fácil de adotar sem uma curva de aprendizado acentuada.
  • Gerenciamento Robusto de Dependências: Fornece resolução precisa de dependências e suporte a arquivos de bloqueio para ambientes reprodutíveis.
  • Ambientes Virtuais Automáticos: Cria e gerencia ambientes virtuais automaticamente, reduzindo a configuração manual.
  • Suporte Multiplataforma: Funciona em macOS, Linux e Windows.
  • Instalação Autônoma: Pode ser instalado sem exigir Python ou Rust, usando um instalador simples ou curl.

uv vs poetry vs pdm vs pip performance comparison

Ainda não está convencido de por que usar o uv?

  • Desempenho: Reduz drasticamente os tempos de instalação de pacotes e resolução de dependências.
  • Simplicidade: Une múltiplas ferramentas em uma única, simplificando a configuração e o gerenciamento de projetos.
  • Confiabilidade: Fornece ambientes consistentes e reprodutíveis com mensagens de erro claras e resolução de conflitos.
  • Padrões Modernos: Suporta pyproject.toml para configuração de projetos, alinhando-se aos padrões atuais de empacotamento Python.

Casos de Uso Exemplo

Vamos tentar algo emocionante!

  • Iniciando um Novo Projeto:
uv init myproject
cd myproject
uv add requests
uv run python script.py

Isso cria um diretório de projeto, configura um ambiente virtual, instala dependências e executa scripts em um ambiente isolado.

  • Gerenciando Scripts com Dependências Inline:
uv add --script script.py requests
uv run script.py

O uv pode gerenciar dependências para scripts de único arquivo sem arquivos de requisitos separados.

Comparação com Ferramentas Tradicionais

Funcionalidade uv pip/virtualenv Poetry
Velocidade Muito rápida Lenta Moderada
Ambientes Virtuais Automático Manual Automático
Resolução de Dependências Avançada Básica Avançada
Gerenciamento de Versões do Python Sim Não (requer pyenv) Não
Suporte a Arquivo de Bloqueio Sim Não (requer pip-tools) Sim
Execução de Scripts Integrada Não Limitada

Como instalar e começar a usar o UV no seu sistema

Para instalar e começar a usar uv no seu sistema, siga estas etapas simples:

Instalação

  1. Instalador Autônomo (Recomendado)
    • Linux/macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh

Ou, se preferir wget:

wget -qO- https://astral.sh/uv/install.sh | sh
  • Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • Versão Específica: Você pode solicitar uma versão específica incluindo-a na URL, por exemplo, https://astral.sh/uv/0.7.15/install.sh.
  1. Alternativa: Instalar via pip (se você tiver Python instalado)
pip install uv

Nota: Este método é menos recomendado para acesso global a menos que você saiba o que está fazendo, pois pode poluir seu ambiente Python do sistema.

  1. Instalar via pipx (para instalação isolada, de escopo do usuário)
pipx install uv

Este método é mais limpo para acesso global se você já usar pipx.

Começando

Para Verificar a Instalação - Execute:

uv

Você deve ver um menu de ajuda confirmando que o uv está instalado e pronto para uso.

Para Criar e Ativar um Ambiente Virtual

  • Criar um venv:
uv venv test
  • Ativar em Linux/macOS:
source test/bin/activate
  • Ativar em Windows:
.\test\Scripts\activate

Agora você pode usar uv pip install para instalar pacotes neste ambiente.

Inicializar um Novo Projeto

uv init

Isso cria um pyproject.toml e .gitignore para seu projeto.

Adicionar Dependências

Adicionar um pacote:

uv add

Isso atualiza o pyproject.toml e gera/atualiza o arquivo de bloqueio.

Sincronizar Dependências

Instalar todas as dependências no seu ambiente:

uv sync

Ou, use a interface compatível com o pip:

uv pip install

Isso garante que todas as dependências sejam instaladas de acordo com seu arquivo de bloqueio.

Executar Scripts

Use:

uv run script.py

Isso gerencia automaticamente o ambiente e as dependências do seu script.

Integração com Shell (Opcional)

Para um fluxo de trabalho mais suave, você pode adicionar a integração com shell ao seu .zshrc ou .bashrc para ativar automaticamente um ambiente virtual padrão e aliasar pip para uv pip.

Com essas etapas, você terá o uv instalado e estará pronto para gerenciar seus projetos Python com velocidade e facilidade.

Instalando Versões Específicas do Python

Você pode usar uv para instalar versões específicas do Python e gerenciá-las para seus projetos.

  • Instalar a versão mais recente estável do Python: 
    uv python install
    Este comando baixa e instala a versão mais recente estável do Python disponível.
  • Instalar uma versão específica: 
    uv python install 3.12
    Isso instala a última versão de patch do Python 3.12 (por exemplo, 3.12.3).
  • Instalar uma versão exata de patch: 
    uv python install 3.12.3
    Isso instala exatamente o Python 3.12.3.
  • Instalar múltiplas versões: 
    uv python install 3.9 3.10 3.11
    Isso instala o Python 3.9, 3.10 e 3.11.
  • Instalar uma versão que corresponda a uma restrição: 
    uv python install '>=3.8,=3.11"
    Isso altera a exigência de versão do Python do projeto.

Notas Adicionais

Downloads Automáticos: Por padrão, o uv fará o download e a instalação das versões necessárias do Python se elas não forem encontradas no seu sistema.

Python do Sistema: O uv pode usar instalações existentes de Python, se presentes, ou você pode forçar o uso do Python do sistema com a bandeira --no-managed-python.

Atualizações: Você pode atualizar as versões do Python gerenciadas pelo uv para a última versão de patch com:

uv python upgrade 3.12

Ou atualizar todas as versões instaladas:

uv python upgrade

Atualizações entre versões menores (por exemplo, 3.12 para 3.13) não são suportadas.

Em resumo, o uv fornece ferramentas flexíveis e poderosas para instalar, gerenciar e usar versões específicas do Python em seus projetos.

Como o UV descobre interpretadores Python disponíveis em diferentes sistemas

O UV descobre interpretadores Python disponíveis em diferentes sistemas verificando um conjunto de locais bem definidos e consultando cada candidato para sua metadados de versão. Aqui está como funciona:

  • Instalações de Python Gerenciadas:
    O UV primeiro verifica o diretório especificado pela variável de ambiente UV_PYTHON_INSTALL_DIR, onde armazena suas próprias versões de Python gerenciadas.
  • Caminho do Sistema (PATH):
    Em macOS e Linux, o UV verifica por executáveis nomeados python, python3 ou python3.x (onde x é um número de versão) em diretórios listados no PATH do sistema. Em Windows, ele busca por python.exe.
  • Locais Específicos do Windows:
    No Windows, o UV também verifica o registro do Windows e interpretadores do Python do Microsoft Store usando a saída de py --list-paths.
  • Ambientes Virtuais:
    Se um ambiente virtual estiver ativo ou especificado, o UV verifica o interpretador nesse ambiente para compatibilidade antes de buscar em outros lugares.
  • Consulta de Metadados:
    Cada executável descoberto é consultado para seus metadados de versão. Apenas executáveis que correspondem à versão solicitada (ou restrição de versão) são considerados. Arquivos que não são executáveis são ignorados.
  • Preferência e Fallback:
    Por padrão, o UV prefere instalações do Python do sistema, mas você pode ajustar isso com opções para preferir versões gerenciadas ou usar apenas versões gerenciadas/sistema. Se nenhum interpretador adequado for encontrado, o UV pode baixar e instalar a versão necessária.

Este processo robusto de descoberta garante que o UV possa localizar e usar o interpretador Python correto de forma confiável em diferentes sistemas operacionais e ambientes.