externally-managed-environment no pip: como resolver

Você configura um servidor novo com Ubuntu 24.04, um Raspberry Pi ou um Mac com Homebrew, digita pip install requests como faz há anos, e o pip para com error: externally-managed-environment. O mesmo comando ainda funciona na sua máquina antiga, e a mensagem pede que você use o apt, um ambiente virtual ou o pipx no lugar.

Este guia explica o que o erro protege, quais sistemas o ativam e as soluções na ordem em que as recomendamos, com a opção que desliga a verificação por último. Rodamos cada comando contra uma reprodução do erro. As últimas seções tratam do pip atrás de um servidor proxy e de uma primeira requisição por um proxy a partir do novo ambiente.

O que significa "error: externally-managed-environment"?#

Significa que o pip encontrou um marcador dizendo que outra ferramenta é dona desta instalação do Python. A PEP 668 define o marcador: um arquivo chamado EXTERNALLY-MANAGED no diretório da biblioteca padrão do interpretador, por exemplo /usr/lib/python3.13/ no Debian 13. O pip lê o arquivo desde a versão 23.0, lançada em janeiro de 2023. Quando o arquivo existe e o pip não está rodando dentro de um ambiente virtual, ele imprime o texto do arquivo e sai sem instalar nada.

Reproduzimos o erro no Windows 11 com o pip 26.2.1: colocamos o texto do marcador do Debian 13 no diretório da biblioteca padrão de um Python 3.14.8 descartável e rodamos python -m pip install requests. A saída é igual à que os usuários do Debian veem:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.13/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

As duas primeiras linhas, a note e o hint vêm do pip. O bloco recuado é o texto do arquivo marcador, então ele muda conforme o sistema: o Arch Linux sugere pacman -S python-xyz, o Homebrew sugere brew install xyz, e os dois também apontam para um ambiente virtual e para o pipx.

Por que o pip se recusa a instalar aqui?#

Porque, sem isso, dois gerenciadores de pacotes escreveriam no mesmo diretório sem saber um do outro. No Debian, no Ubuntu ou no Arch, partes do sistema operacional são escritas em Python e importam bibliotecas que o gerenciador de pacotes do sistema instalou. Esse gerenciador registra de quais versões esses programas precisam; o pip não lê esses registros. A PEP 668 descreve o resultado: um pip install pode atualizar ou remover uma biblioteca que veio com o sistema operacional e até quebrar o próprio gerenciador de pacotes do Fedora, o dnf.

Mandar o pip para um diretório separado também não resolve. As distribuições colocam pacotes instalados localmente em lugares como /usr/local, e no layout que a PEP 668 recomenda as instalações locais têm prioridade sobre os pacotes da distribuição, então os programas Python do sistema importam o que o pip tiver deixado ali. O marcador encerra a questão: os projetos ganham os próprios ambientes, e o Python do sistema fica como a distribuição o construiu.

Como o pip decide bloquear uma instalação?#

1. Ele verifica se está em um ambiente virtual. Dentro de um venv, sys.prefix é diferente de sys.base_prefix, a verificação termina e a instalação segue.
2. Ele procura o marcador no diretório que sysconfig.get_path("stdlib") retorna.
3. Ele lê a mensagem da chave Error do arquivo, ou de uma chave traduzida Error-<idioma> se o arquivo tiver uma, e a imprime.
4. Ele bloqueia tanto pip install quanto pip uninstall. --user não ajuda: pip install --user requests parou com o mesmo erro no nosso teste. Rodar o pip com sudo não muda nada.
5. A opção --break-system-packages pula a verificação, assim como as formas dela em variável de ambiente e em arquivo de configuração, que veremos mais abaixo.

Para saber em qual caso você está, pergunte ao interpretador que você vai usar:

python3 -c "import os, sys, sysconfig; print('venv:', sys.prefix != sys.base_prefix); print('marker:', os.path.isfile(os.path.join(sysconfig.get_path('stdlib'), 'EXTERNALLY-MANAGED')))"

O pip só bloqueia a instalação quando isso imprime venv: False e marker: True. Dentro de um ambiente virtual, o marcador do interpretador base continua visível, então o nosso venv também imprimiu marker: True, mas a primeira linha dizia venv: True e o pip instalou normalmente.

Quais sistemas trazem o marcador?#

Debian, Ubuntu, Raspberry Pi OS, Arch Linux e Homebrew trazem; o Fedora e as imagens oficiais do Docker, não.

O Debian marcou o pacote do Python 3.11 antes do lançamento do Debian 12, e o Ubuntu 23.04 trouxe esse mesmo pacote; por isso o Ubuntu 24.04 LTS e os sistemas Ubuntu ou Debian que muita gente roda no WSL do Windows mostram a mesma mensagem. O Fedora segue outro caminho: não traz marcador e manda o sudo pip install para /usr/local.

Solução 1: crie um ambiente virtual para o seu projeto#

Um ambiente virtual (venv) é um diretório com o próprio python e a própria pasta de pacotes, ligado ao interpretador do sistema, mas separado dos pacotes dele. Dentro dele, o pip pula a verificação da PEP 668, e nada do que você instalar ali consegue mexer no sistema.

cd ~/my-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests

No nosso teste, o último comando terminou com:

Successfully installed certifi-2026.7.22 charset_normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0

Ativar o ambiente só coloca o diretório bin dele no início do seu PATH. A documentação do venv no Python mostra o comando para cada shell, com .venv\Scripts\activate no Windows. Você pode pular a ativação e chamar o interpretador do ambiente diretamente, que é a forma mais segura em scripts, tarefas cron e unidades do systemd:

.venv/bin/python -m pip install requests
.venv/bin/python app.py

Trate o .venv como descartável. Deixe-o fora do Git (desde o Python 3.13, o venv grava um .gitignore dentro da pasta), registre os seus pacotes com python -m pip freeze > requirements.txt e reconstrua o ambiente em outro lugar com python -m pip install -r requirements.txt. Um venv não sobrevive a ser movido ou copiado para outra máquina; crie-o de novo lá.

No VS Code, a extensão do Python encontra uma pasta .venv no espaço de trabalho e dá preferência a ela. Se ela escolher outro interpretador, execute Python: Select Interpreter (Python: selecionar interpretador) na Paleta de Comandos (Command Palette; Ctrl+Shift+P, ou Cmd+Shift+P no Mac) e escolha o que está dentro de .venv; a partir daí, os novos terminais abrem com o ambiente ativo.

"ensurepip is not available" no Debian e no Ubuntu#

O Debian distribui o suporte ao venv em um pacote separado, então, em um servidor mínimo, o próprio comando python3 -m venv .venv pode falhar. O módulo venv modificado pelo Debian imprime esta mensagem, com o número de versão do seu Python:

The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.13-venv

Instale o pacote (python3-venv puxa o da versão específica), apague a pasta criada pela metade e rode o comando de novo:

sudo apt install python3-venv
rm -rf .venv
python3 -m venv .venv

Solução 2: instale ferramentas de linha de comando com o pipx#

Se você quer um programa, e não uma biblioteca, como um formatador, um linter ou um cliente HTTP, use o pipx, a ferramenta que a própria mensagem de erro sugere. O pipx cria um ambiente virtual por aplicação e coloca os comandos dela no seu PATH, então as ferramentas nunca quebram as dependências umas das outras.

sudo apt install pipx      # macOS: brew install pipx
pipx ensurepath
pipx install ruff

Abra um terminal novo depois de pipx ensurepath. No nosso teste, pipx install ruff informou installed package ruff 0.17.0 e o comando ruff funcionou na hora; depois, pipx upgrade ruff e pipx uninstall ruff cuidam dele. O guia de instalação do pipx traz os comandos para outros sistemas.

Solução 3: use o pacote da própria distribuição#

Para uma biblioteca de que um script do sistema precisa, a distribuição talvez já tenha um pacote. Debian, Ubuntu e Raspberry Pi OS chamam as bibliotecas Python de python3-<nome>; o Arch usa python-<nome>:

sudo apt install python3-requests     # Debian, Ubuntu, Raspberry Pi OS
sudo pacman -S python-requests        # Arch Linux

Essas versões recebem as atualizações de segurança da distribuição, mas costumam ser mais antigas que a última versão no PyPI. O Homebrew empacota aplicações, e a documentação dele indica um venv para bibliotecas.

Às vezes um projeto precisa das duas coisas: uma biblioteca de hardware do apt em um Raspberry Pi e um pacote mais novo do PyPI. Crie o ambiente com python3 -m venv --system-site-packages .venv. O venv passa a enxergar os pacotes do sistema, e o pip continua instalando só no venv. No nosso teste, o requests foi para o .venv, enquanto uma biblioteca do sistema já instalada era carregada da pasta do sistema.

Solução 4: use o uv para ambientes e ferramentas#

O uv é um gerenciador de pacotes e projetos que substitui vários comandos do pip, do venv e do pipx por um único programa. Ele também respeita o marcador: uv pip install --system no nosso Python marcado parou com error: The interpreter at … is externally managed, seguido do mesmo texto do Debian. O fluxo normal dele usa um ambiente virtual, então o erro não aparece:

uv venv
uv pip install requests
uv tool install ruff

uv venv cria o .venv na pasta atual, uv pip install instala nele sem ativação e uv tool install é o equivalente de pipx install. Os três funcionaram no nosso teste.

Contêineres e pipelines de CI#

As imagens oficiais python do Docker Hub compilam o próprio Python em /usr/local e não trazem marcador, então pip install funciona nelas como antes. O erro aparece quando um Dockerfile parte de uma imagem debian ou ubuntu e instala o Python com apt. A solução é a mesma do notebook: instale python3-venv, crie o ambiente com RUN python3 -m venv /opt/venv e adicione ENV PATH="/opt/venv/bin:$PATH". Todo RUN pip install -r requirements.txt posterior e o python do contêiner passam a usar o venv, como fariam depois de uma ativação.

Sistemas de CI costumam abrir um shell novo a cada etapa, então uma ativação anterior se perde. Chame o interpretador do ambiente pelo caminho (.venv/bin/python -m pip install …, .venv/bin/python -m pytest) em cada etapa.

Por que --break-system-packages é o último recurso?#

A opção desliga a proteção em vez de resolver o conflito, e funciona: na nossa reprodução, pip install --break-system-packages requests instalou o pacote no Python marcado, assim como a variável de ambiente PIP_BREAK_SYSTEM_PACKAGES=1 e a linha break-system-packages = true na seção [global] de um arquivo de configuração do pip. Ela não torna a instalação segura; só remove o aviso, e o pip agora pode atualizar ou remover uma biblioteca que as próprias ferramentas do sistema importam. Uma atualização posterior do sistema pode então sobrescrever o que o pip instalou.

Apagar o arquivo EXTERNALLY-MANAGED tem o mesmo efeito para todos os usuários e programas da máquina. Se você realmente precisa desligar a verificação, faça isso onde o estrago fica contido, como um contêiner que você reconstrói ou uma máquina virtual, e nunca em um perfil de shell ou em uma configuração global do pip, onde ela vale silenciosamente para toda instalação posterior.

Como usar o pip atrás de um servidor proxy?#

Passe a URL do proxy ao pip com --proxy, com a variável HTTPS_PROXY ou no arquivo de configuração dele. Redes de empresas e universidades muitas vezes só liberam o tráfego web por um servidor proxy que pede usuário e senha, e o pip não aponta a falta de login como um problema de proxy. Sem credenciais, o nosso proxy de teste local respondeu a cada tentativa com o status 407, e o pip imprimiu cinco novas tentativas (quatro removidas abaixo) e uma conclusão enganosa:

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'OSError('Tunnel connection failed: 407 Proxy Authentication Required')': /simple/requests/
ERROR: Could not find a version that satisfies the requirement requests (from versions: none)
ERROR: No matching distribution found for requests

from versions: none significa que o pip nunca chegou ao índice de pacotes, e não que o pacote não existe. O guia do usuário do pip lista todas as opções; estas três cobrem a maioria dos casos:

# para um único comando
python -m pip install --proxy http://user:pass@proxy.example.com:8080 requests

# para todos os comandos neste shell
export HTTPS_PROXY=http://user:pass@proxy.example.com:8080

# salvo só no ambiente virtual ativo
python -m pip config --site set global.proxy http://user:pass@proxy.example.com:8080

As três instalaram o requests pelo nosso proxy de teste. Com --site, o pip gravou a configuração no arquivo de configuração do próprio venv (pip.conf, ou pip.ini no Windows); sem essa opção, pip config set grava no seu arquivo de usuário, que vale para todos os ambientes. Se a senha tiver @, : ou /, aplique a codificação percentual (percent-encoding) a esses caracteres; Como corrigir HTTP 407 Proxy Authentication Required explica a codificação e outros erros de credenciais.

Atrás de um proxy que inspeciona o tráfego HTTPS, o próximo erro costuma ser CERTIFICATE_VERIFY_FAILED. Desde a versão 24.2, o pip também confia nos certificados do sistema operacional, então um certificado raiz da empresa que a equipe de TI instalou no repositório do sistema muitas vezes resolve, e --cert aponta o pip para um arquivo de bundle. Unable to Get Local Issuer Certificate: como resolver explica como diferenciar as causas.

Como enviar uma primeira requisição por um proxy a partir do venv?#

Com o requests instalado no venv, uma requisição por um proxy precisa de um único dicionário. O script lê a URL do proxy de uma variável de ambiente, então as credenciais ficam fora do código:

import os
import sys

import requests

# O endpoint e as credenciais do seu painel de proxy
PROXY = os.environ.get("PROXY_URL", "http://user:pass@pr.proxynet.io:8000")
proxies = {"http": PROXY, "https": PROXY}

print("Python:", sys.executable)
try:
    r = requests.get("https://example.com/", proxies=proxies, timeout=15)
    print("Status:", r.status_code)
except requests.exceptions.ProxyError as err:
    print("Proxy error:", err)

Rode o script com .venv/bin/python first_request.py. Pelo nosso proxy de teste local, a linha Python: mostrou o interpretador dentro de .venv e a segunda linha dizia Status: 200. Com uma senha errada, ele imprimiu um Proxy error terminando em Tunnel connection failed: 407 Proxy Authentication Required. Iniciado com o python3 do sistema, o script nem chegou tão longe: ModuleNotFoundError: No module named 'requests', porque os pacotes ficam no venv.

O tipo de proxy decide como os sites de destino veem as suas requisições. Os Proxies residenciais saem por conexões residenciais no país e na cidade que você escolher, com um endereço novo a cada requisição ou uma sessão fixa de 1 a 60 minutos; use-os para ver as páginas como os visitantes locais as veem, dentro dos termos e dos limites de taxa de cada site.

Os Proxies de datacenter dão a você endereços IPv4 dedicados com tráfego sem cota, o que combina com tarefas constantes, como verificar os seus próprios serviços e APIs a partir de vários países. Para enviar dados em vez de buscá-los, POST com JSON no Python Requests: equivalentes do cURL explica o json=, os cabeçalhos e os comandos cURL equivalentes.

Onde você encontra esse erro#

• Servidores novos e imagens de VPS com Debian 12 ou posterior ou com Ubuntu 24.04, em que scripts de configuração antigos ainda chamam sudo pip install.
• Projetos com Raspberry Pi que seguem tutoriais antigos para bibliotecas de sensores e GPIO.
• Macs em que o python3 vem do Homebrew.
• Dockerfiles baseados em imagens debian ou ubuntu que instalam o Python com apt.
• WSL no Windows, que roda Ubuntu ou Debian.
• Jobs de CI depois que a imagem base passa para uma versão mais nova.

Erros comuns#

• Rodar sudo pip install dentro de um venv ativado. No Debian, o sudo troca o PATH por uma lista fixa (secure_path), encontra o pip do sistema e o erro volta. Um venv na sua pasta pessoal não precisa de sudo.
• Instalar no venv, mas rodar com python3. O interpretador do sistema não enxerga os pacotes do venv e falha com ModuleNotFoundError.
• Fazer commit do .venv no Git ou copiá-lo para outra máquina. Reconstrua o ambiente a partir do requirements.txt.
• Definir break-system-packages em uma configuração global do pip. Isso desliga a proteção para toda instalação posterior.

Guia de decisão#

Perguntas frequentes#

Por que o pip install parou de funcionar depois que atualizei o Ubuntu ou o Debian?#

A sua nova versão traz o marcador EXTERNALLY-MANAGED, e o pip 23.0 e versões posteriores o respeitam. O Debian 12 e o Ubuntu 23.04 foram as primeiras versões com o arquivo, então subir do Debian 11 ou do Ubuntu 22.04 é o gatilho mais comum.

É seguro usar --break-system-packages?#

Não em um sistema que você quer manter. A opção deixa o pip substituir ou remover bibliotecas que as próprias ferramentas Python do sistema operacional importam. Use-a só em um contêiner ou em uma máquina virtual que você possa reconstruir.

O pip install --user evita o erro?#

Não. A verificação olha o interpretador, não a pasta de usuário para onde os arquivos iriam, então as instalações com --user também são bloqueadas; o nosso teste confirmou isso.

Posso apagar o arquivo EXTERNALLY-MANAGED?#

Pode, mas isso desliga a proteção para todos os usuários e programas da máquina, exatamente como um --break-system-packages global, e uma atualização posterior do pacote do Python pode restaurar o arquivo. Um venv resolve o problema sem nenhum desses dois efeitos colaterais.

Preciso ativar o ambiente virtual toda vez?#

Não. A ativação muda o PATH só no shell atual. Chamar .venv/bin/python (.venv\Scripts\python.exe no Windows) usa o ambiente diretamente, e essa é a forma confiável para scripts, serviços e CI.

Por que o pip ainda mostra o erro dentro do meu ambiente virtual?#

Porque o pip que você rodou não é o pip do venv: sudo, um terminal novo sem ativação ou o terminal de um editor que usa o interpretador do sistema. Rode python -m pip --version; o caminho que ele imprime deve apontar para dentro de .venv.

Em resumo#

error: externally-managed-environment é o sistema operacional dizendo ao pip que não cabe a ele mudar o Python do sistema. Dê a cada projeto um ambiente virtual, dê a cada ferramenta de linha de comando o seu próprio pelo pipx e deixe o Python do sistema com o apt, o pacman ou o Homebrew. Reserve --break-system-packages para máquinas que você pode descartar. Quando esses scripts precisarem acessar sites a partir de outros locais, veja a nossa página de serviços de proxy.