Um ano usando uv: prós, contras e o que considerar na migração

• Depois de usar o uv por um ano em vários ambientes de cliente, ele simplificou bastante o início de projetos Python e o gerenciamento de dependências, então vale a pena tentar primeiro sempre que o ambiente permitir
• Mantendo quase todo o workflow com pip/venv já existente, ele funciona de forma mais rápida e estável, o que torna o custo de migração relativamente baixo
• Ao reunir instalação do Python, ambiente virtual, arquivo de lock, execução, build e execução de ferramentas temporárias em uma só ferramenta, ele reduz bastante o custo de experimentação em projetos
• Por outro lado, falhas na resolução de dependências legadas, o alcance de suporte do python-build-standalone, cache que pode passar de 20 GB, políticas de segurança corporativa e a barreira da CLI são limitações reais
• Se você vai continuar trabalhando com Python, mesmo usando uv ainda precisa conhecer pip e venv, para se preparar para ambientes em que uv não seja permitido ou não se encaixe

---

Onde começa a dificuldade dos projetos Python

• A principal raiz dos problemas em Python está no bootstrapping: preparar o próprio Python e iniciar um projeto novo
• Boa parte dos problemas de empacotamento que aparecem depois também vem da instalação inicial do Python e da configuração do projeto, mais do que da instalação de dependências ou do build dos pacotes em si
• A forma de instalar Python varia conforme o sistema operacional, e os padrões e armadilhas também são diferentes
• Apesar de ser uma linguagem adequada para iniciantes, instalar Python exige bastante conhecimento prévio
• Python é usado por grupos muito diversos, como estudantes, cientistas de dados, desenvolvedores de IA, desenvolvedores web, administradores de sistemas, biólogos, geógrafos e desenvolvedores de plugins
• As diferenças de ambiente de execução são enormes entre um PC corporativo com Windows, um notebook pessoal com Debian, universidade, órgão público, startup, exército, laboratório de pesquisa ou grande empresa, então é difícil cobrir tudo com um único tutorial
• PATH, PYTHONPATH, convivência entre várias versões de Python, pacotes opcionais no Linux, Python como dependência do sistema e a popularidade de extensões compiladas aumentam ainda mais a complexidade
• Uma boa ferramenta de gerenciamento de projetos Python precisa atender às seguintes condições
  • Deve funcionar de forma independente do bootstrapping do Python
  • Deve unificar a instalação e a execução do Python entre plataformas e contextos diferentes
  • Deve servir de ponte com ferramentas básicas como pip e venv
  • Deve ter um resolvedor de dependências forte
  • Deve facilitar instalações simples e também permitir tarefas complexas, como instalar dependências travadas para outro sistema operacional
  • Deve ser fácil de instalar e usar, e confiável o suficiente para assumir partes importantes da stack

A abordagem de bootstrapping do uv

• uv é instalado e atualizado de forma totalmente independente do Python, e a instalação do uv não interfere na instalação do Python, nem o contrário
• Problemas de bootstrapping do Python, PATH e import não afetam o próprio uv
• Isso reduz confusões como onde instalar no sistema ou no ambiente virtual, ou como novas palavras-chave e descontinuações podem afetar o uv
• O uv primeiro ofereceu interfaces compatíveis com pip e venv, para poder ser usado junto com projetos, ferramentas e formas de pensar já existentes
  • Foi uma escolha levando em conta a comunidade existente e código legado
  • O usuário não precisa aprender uv run, uv add ou uvx para usá-lo num workflow parecido com pip e venv
  • Só a velocidade e a confiabilidade nas tarefas básicas já dão motivo para migrar
• Ele também oferece instalação de Python
  • Instala da mesma forma em todos os sistemas operacionais
  • Não exige privilégios de administrador
  • Funciona de forma independente do Python do sistema
  • Instalar várias versões não gera conflito
  • Fornece a mesma biblioteca padrão e inclui tkinter
  • Também inclui versões Pypy, No-GIL e TCO
  • Funciona sem shim, compilação ou padrões arbitrários

Experiência de instalação do Python e python-build-standalone

• O exemplo uv python install pypy3.8 instala o Python 3.8.16 em apenas 2,71 segundos
• Da mesma forma, isso também pode ser executado em Mac ou Windows
• Não aparecem problemas como pacotes ausentes ligados a Tcl, OpenSSL ou Gzip, conflito com outras instalações de Python, paradigmas diferentes por sistema operacional, comandos ausentes ou PATH configurado errado
• A instalação de Python no uv usa python-build-standalone, projeto que a Astral assumiu e vem aprimorando
• A Astral também tenta devolver essas vantagens para o projeto principal do cPython e vem contribuindo com projetos open source adjacentes

Recursos de gerenciamento de projeto

• uv init cria por padrão um repositório git com .venv, pyproject.toml, .gitignore para Python, README.md e hello.py
• As dependências de raiz podem ser declaradas no pyproject.toml ou adicionadas com uv add
• uv remove limpa corretamente o repositório
• uv lock --upgrade-package <package>==<version> permite atualizar pacotes com cuidado, um por vez
• uv build cria um pacote .whl a partir do projeto, mas o uv não exige que o projeto necessariamente seja buildável
• uv run executa comandos dentro do ambiente virtual mesmo sem ele estar ativado
  • O usuário nem precisa saber que o ambiente virtual existe ou entender o conceito de ativação
• Esses comandos atualizam o arquivo de lock de forma automática e transparente
  • Como o uv é rápido, quase não se percebe que a atualização aconteceu
  • O usuário nem precisa saber o que é um arquivo de lock
• O arquivo de lock é multiplataforma, então dá para desenvolver no Windows e fazer deploy no Linux

Desempenho, estabilidade e mensagens de erro

• O desempenho do uv reduz o custo de instalar dependências e experimentar em projetos
• Como é rápido recomeçar do zero, fica fácil repetir várias tentativas sem muito atrito
• Ferramentas como pyenv, pipenv e poetry às vezes quebravam com stack traces em vários ambientes, mas o uv se mostrou muito robusto
• Em termos de qualidade da Astral, três pontos se destacam
  • Correções de bug rápidas e boa resposta a feedback e relatórios
  • Cultura forte de testes, com a suite de testes de resolução de dependências fornecida como pacote separado
  • Mensagens de erro muito boas
• O exemplo uv add httpie==2 mostra passo a passo que httpie==2.0.0 depende de requests>=2.22.0, mas o projeto depende de requests==1, então os requisitos não podem ser satisfeitos
• As mensagens de erro de resolução de dependências têm influência do pubgrub, mas as mensagens do uv como um todo seguem a mesma direção
• Em contexto educacional, ao usar uv, os alunos conseguiram ser produtivos sem grande intervenção, algo que não aconteceu com outras ferramentas
• Projetos profissionais novos conseguiram aproveitar facilmente as vantagens do uv, mas em projetos legados podem aparecer bloqueios

uvx e novas formas de uso

• O uv fornece preparação e isolamento de Python e dependências como blocos básicos fortes e rápidos
• Antes, preparar Python e dependências era uma limitação lenta e sujeita a falhas; com o uv, isso pode ser tratado como um recurso para ajustar workflows
• uv run --with jupyter jupyter notebook executa Jupyter no projeto atual, mas sem adicionar Jupyter e suas dependências ao projeto
• uvx --with pendulum -p 3.13t python baixa e instala um novo build No-GIL do Python, cria um ambiente virtual temporário, instala pendulum e depois inicia o shell do Python
• uvx é como um npx para Python, e pode ser visto como uma forma de fazer o pipx direito
• O suporte a dependências inline muda a forma de usar dependências em pequenos scripts Python
  • Antes, era comum evitar dependências em scripts pequenos ou recorrer a soluções improvisadas e incômodas
  • Agora é possível usar dependências de forma rápida, transparente e autoexplicativa
• Esses recursos não são impostos ao usuário; podem ser descobertos e adotados quando fizerem sentido

Onde o uv falha ou incomoda

• O uv não consegue resolver no lugar do usuário problemas reais de empacotamento
  • Questões como marcadores de versão incorretos, ausência de wheel ou conflito de nomes estão fora do controle do uv
  • Esses problemas são inerentes à qualidade dos dados publicados no PyPI
  • Se problemas de empacotamento parecem menores com uv, é porque ele acerta outras partes do processo
• Por causa do resolvedor de dependências mais rígido, ambientes virtuais de projetos legados que dependiam da resolução frouxa do pip antigo podem quebrar
  • Em um caso com uma base de código de 15 anos recém-migrada para Python 3 e sustentada por um histórico bagunçado de pip freeze, o uv não funcionou
• A instalação embutida de Python do uv fica limitada às versões compiladas com python-build-standalone
  • Instaladores do python.org, deadsnake e pyenv conseguem instalar mais versões de Python
  • Isso pode ser um problema em projetos antigos que exigem uma versão específica
  • Ainda assim, o uv também funciona bem com Python instalado externamente, então não é um bloqueio total
• Os executáveis do python-build-standalone podem ser um pouco mais lentos
  • No pyperformance, o Python 3.10 do uv foi 3% mais lento que o Python do Ubuntu
  • Também pode haver interesse em usar um Python compilado com otimizações específicas de hardware
• O espaço ocupado pelo cache também pode ser um ponto negativo
  • Depois de um ano de uso, o cache do uv ocupava mais de 20 GB em disco
  • Dá para apagar com uv cache clean, mas isso elimina a vantagem de velocidade
  • Diferente do pip, o uv usa hard links para que os pacotes ocupem espaço só uma vez, então ainda pode acabar usando menos espaço que vários ambientes virtuais antigos
• Houve o incômodo de $UV_PYTHON forçar a versão do Python em vez de apenas definir a versão padrão, e a issue correspondente está sendo tratada
• O uv é open source, mas é um produto da empresa comercial Astral
  • A Astral ainda não é lucrativa e ainda não revelou seu produto comercial
  • Há quem ache que é preciso cautela antes de confiar a ela partes importantes da stack
  • Por outro lado, tanto o custo de migrar para uv quanto o custo de sair dele são baixos
• A maior limitação está na adoção em empresas
  • Em ambientes corporativos grandes, rígidos e muito travados em segurança, instalar novas dependências pode ser muito difícil
  • Se o departamento de segurança de TI controla o que pode ser feito nas máquinas, talvez nem permita instalar uv
  • Até chegar a uma versão estável e atender várias exigências, o uso em ambiente corporativo tende a ser limitado
• A CLI também é uma barreira
  • Não são poucos os usuários de Python que não têm familiaridade com linha de comando, especialmente no Windows
  • Esse é um dos motivos para o Anaconda ter interface gráfica
  • Exigir uma ferramenta de CLI cria uma barreira de entrada para iniciantes absolutos
• uvx e uv tool install incentivam a instalar ferramentas fora do projeto, como o pipx
  • Isso funciona bem para ferramentas independentes como yt-dlp e httpie
  • Já ferramentas de desenvolvimento sensíveis à versão do Python ou à sintaxe das bibliotecas, como mypy, podem causar problemas se forem instaladas com uma versão de Python diferente da do projeto

Quando evitar o uv

• Há cinco situações em que não se deve usar uv
  • Existe um projeto legado que não funciona com a resolução de dependências do uv, e não há tempo ou vontade de organizá-lo para migrar
  • O ambiente corporativo não permite usar uv
  • Você ainda não confia nele por não estar em versão estável, por a Astral ainda não ter lançado seu produto comercial ou por haver poucos contribuidores em Rust
  • É preciso uma versão específica de Python que o uv não oferece, e você não quer usar uv junto com um Python instalado externamente
  • A CLI é um obstáculo grande demais para a equipe
• As questões de confiança e de versão específica de Python são mais escolhas do que bloqueios técnicos
• As restrições de ambiente corporativo deixam pouca margem de ação para o usuário
• Na prática, os pontos centrais a considerar são dependências legadas e a barreira da CLI
• O conselho é simples
  • Sempre tente uv primeiro
  • Se não funcionar, volte ao método anterior ou procure uma alternativa
• Se a CLI for o problema, pode-se usar o instalador do python.org para preparar o Python e sugerir plugins de IDE que encapsulem o uv
• Quem sabe programar provavelmente consegue aprender o básico de linha de comando necessário para usar uv

Posição daqui para frente

• Para uso corporativo, ainda existe uma distância até a v1, e a versão estável é importante porque empresas não conseguem atualizar com frequência
• É esperado que surjam recursos de empacotamento que possam servir como alternativa a pex/shiv, além de um backend de build
• Um recurso para gerar instaladores de aplicações parece uma conclusão lógica, mas é muito mais complexo, já que só lidar corretamente com assinatura já é difícil
• Quando o suporte a tasks estiver melhor organizado, as funcionalidades já devem ser suficientes para necessidades pessoais
• Se Python faz parte do seu trabalho, ainda é preciso aprender a usar pip e venv
  • Porque em algum momento você pode encontrar um ambiente em que não seja possível usar uv
• Em resumo, o uv tem baixo custo e grande benefício, então, nos ambientes em que puder ser usado, vale como uma solução de Pareto para tentar primeiro