O "error: externally-managed-environment" do pip e a PEP 668

O que é

error: externally-managed-environment é a resposta do pip (versão 23.0 e posteriores) ao encontrar um arquivo marcador EXTERNALLY-MANAGED no diretório da biblioteca padrão da instalação de Python de destino; o bloco logo abaixo começa com × This environment is externally managed. Fora de um ambiente virtual, ele bloqueia também o pip install --user. A PEP 668 define esse marcador: quem distribui o Python (uma distribuição Linux, mas também o conda ou um sistema semelhante) o coloca para declarar que aquela instalação de Python é gerenciada por algo que não é o pip, e que por isso o pip não deve instalar, atualizar nem remover pacotes nela diretamente. A página de especificação do Python Packaging User Guide documenta o mesmo marcador e o comportamento recomendado para os instaladores. A mensagem vem do pip, não do Python; o próprio arquivo marcador pode conter o texto com a solução sugerida pelo distribuidor, e vale a pena lê-lo antes de aplicar uma correção genérica.

Por que importa

Antes da PEP 668, um pip install fora de um ambiente virtual podia sobrescrever ou sombrear em silêncio um pacote que o gerenciador de pacotes do próprio sistema operacional também controla e do qual depende, quebrando ferramentas do sistema construídas para uma versão específica. O marcador transforma isso em uma falha explícita, em vez de uma corrupção silenciosa, ao custo de quebrar scripts e imagens de contêiner que presumiam instalações globais sem restrições.

Como aplicar

• Diagnóstico: encontre o marcador com python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))" e procure EXTERNALLY-MANAGED nesse diretório; o conteúdo do arquivo costuma indicar a solução preferida pela distribuição.
• Soluções, da menos para a mais invasiva:
  1. Use um ambiente virtual para o projeto: python3 -m venv .venv && source .venv/bin/activate && pip install ... — isola por completo as instalações do interpretador gerenciado e é a solução para a qual a PEP 668 foi pensada para conduzir.
  2. Instale uma ferramenta de linha de comando independente com pipx install <tool>, que cria um ambiente isolado próprio para cada ferramenta.
  3. Instale a versão empacotada pela própria distribuição, usando o gerenciador de pacotes dela (por exemplo, apt install python3-<name>), quando ela existir.
  4. Somente dentro de um ambiente descartável, criado para uma única finalidade (uma imagem de contêiner temporária, uma etapa de CI que nunca reaproveita o interpretador depois), force a instalação com pip install --break-system-packages ... (pip 23.0.1+, ou PIP_BREAK_SYSTEM_PACKAGES=1) — um último recurso inseguro, que pode sobrescrever arquivos pertencentes ao gerenciador de pacotes do sistema, e não uma flag padrão para adicionar em todo lugar.
• Inseguro/enganoso: apagar o arquivo EXTERNALLY-MANAGED. Isso silencia o aviso sem isolar nada, e uma atualização da distribuição pode simplesmente recolocá-lo.

Armadilhas

• Adicionar --break-system-packages a um host compartilhado ou de longa duração "só para o erro parar" transforma cada instalação futura exatamente no conflito que o marcador existe para evitar.
• Presumir que o marcador é um bug do pip; ele é uma política deliberada da distribuição, que o pip respeita.