Tutoriais de VPS
Corrigir externally-managed-environment do pip com venv ou pipx
Se o Python do sistema bloqueia a instalação, diferencie bibliotecas do projeto, aplicativos CLI e pacotes do sistema. Escolha venv ou pipx e confira ensurepip e imports de serviços.

Ao executar pip install -r requirements.txt no VPS, aparece error: externally-managed-environment. Isso normalmente indica que o gerenciador de pacotes do sistema mantém essa instalação do Python e o pip não deve alterá-la diretamente. Em geral, não é um problema de rede, mirror ou permissão.
Use um venv próprio para o projeto, considere pipx para um aplicativo independente de linha de comando e prefira apt para componentes do sistema. Escolher o ambiente adequado evita uma instalação forçada que depois quebre ferramentas ou outros projetos.
No diretório do projeto, execute:
command -v python3
python3 --version
python3 -m pip --version
python3 -c "import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)"
python3 -m pip vincula o pip ao interpretador escolhido, evitando confusão quando pip e pip3 apontam para outra instalação. Caminhos iguais nas duas últimas linhas normalmente indicam ausência de venv; caminhos diferentes indicam ambiente virtual. Se o pip não estiver instalado, o erro será No module named pip, que é outro problema.
A especificação de empacotamento do Python usa EXTERNALLY-MANAGED para marcar um interpretador gerenciado externamente. Isso não significa que o Python esteja quebrado, nem que você deva apagar o marcador. sudo pip e pip install --user não são soluções gerais para esse erro.
| O que você precisa | Onde instalar | Como usar |
|---|---|---|
| Dependências de site, API ou projeto de scripts | Venv do próprio projeto | Executar com .venv/bin/python |
| Aplicativo Python independente de linha de comando | pipx | Usar o executável exposto pelo pipx |
| Componente do sistema empacotado pela distribuição | apt ou equivalente | Seguir a documentação da distribuição |
O pipx mantém um ambiente isolado e disponibiliza os comandos de cada aplicativo; veja o guia de aplicativos CLI da PyPA. Ele não substitui a instalação de um requirements.txt arbitrário de projeto.
Em um projeto Linux existente, entre no diretório que contém o requirements.txt confiável:
python3 -m venv .venv
.venv/bin/python -m pip --version
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check
Se .venv já existe, confira interpretador, dependências e serviços antes de substituí-lo. Crie um ambiente novo com uma versão suportada pelo projeto, não com outra versão principal apenas para concluir a instalação.
Respeite o lockfile ou as instruções de implantação. Restaurar um serviço não é motivo para atualizar todos os pacotes; instalar sem erro ainda pode introduzir incompatibilidades na aplicação.
O caminho explícito do interpretador funciona sem ativação. A documentação de venv explica que ativar muda principalmente o PATH do shell atual; chamar seu Python diretamente também funciona.
Para uso interativo no Bash ou Zsh:
source .venv/bin/activate
python -m pip --version
python -c "import sys; print(sys.executable)"
deactivate
Python e pip devem resolver dentro de .venv. deactivate restaura as configurações do shell; não desinstala pacotes nem exclui o ambiente. Depois execute os testes de importação, inicialização ou saúde do projeto. Um pip check bem-sucedido verifica dependências declaradas, não o funcionamento da aplicação.
Ubuntu ou Debian mínimos podem mostrar ensurepip is not available. Com o python3 padrão da distribuição, instale suporte de venv pelo repositório:
sudo apt update
sudo apt install python3-venv
Depois crie o ambiente. A documentação de Python do Ubuntu também descreve python3-full, que inclui suporte de venv. Escolha conforme o componente ausente; não remova o Python do sistema para instalar dependências.
Um interpretador de outro repositório, compilado, do pyenv ou de um painel pode não corresponder a python3-venv. Confirme qual Python cria o ambiente e obtenha suporte da mesma origem. Não altere o link /usr/bin/python3 para acomodar um único projeto.
Falhas de certificado, timeout, versão incompatível e compilação de extensões pertencem a outra camada. Confira índice, rede, versão do Python, plataforma e dependências de compilação. Aumentar permissões ou apagar o marcador não resolve esses erros.
Em Ubuntu ou Debian com pipx no repositório, instale a ferramenta primeiro:
sudo apt install pipx
pipx ensurepath
pipx list
Siga a documentação oficial do aplicativo para pipx install 应用的发行包名. O pacote deve realmente fornecer uma CLI, não ser uma biblioteca qualquer. Depois de ensurepath, pode ser necessário reconectar por SSH ou abrir outro shell para o PATH encontrar o comando.
Instalar com pipx não torna o pacote importável pelo Python de um site; são ambientes separados. Se seu código precisa import uma biblioteca, instale-a no venv do projeto. Nomes de pacotes do sistema, distribuições PyPI e módulos importados podem diferir; não adivinhe a instalação apenas pelo nome do módulo ausente.
A ativação afeta somente o shell atual. Outro usuário, uma nova conexão SSH ou um serviço não a herdam automaticamente.
Para o projeto em /srv/myapp, configure o serviço para chamar /srv/myapp/.venv/bin/python, com diretório de trabalho, usuário e variáveis corretos. Um serviço web pode usar sua entrada real, como /srv/myapp/.venv/bin/gunicorn, sem presumir que um python sem caminho encontre o venv.
Não trate source .venv/bin/activate como um executável comum no ExecStart do systemd. Veja o guia de implantação Python e o diagnóstico de serviços systemd.
Ao migrar de VPS, evite copiar diretamente .venv. Ambientes virtuais podem conter caminhos absolutos e arquivos específicos da plataforma. Preserve projeto, dependências fixadas e configurações; recrie o ambiente no destino e verifique o serviço.
As opções de instalação do pip definem essa opção como permissão para modificar Python gerenciado externamente. Ela contorna a restrição, mas não isola projetos nem garante compatibilidade com pacotes mantidos pelo apt.
Use venv para projetos, pipx para CLI e pacotes da distribuição para componentes do sistema. Se já houve instalação forçada, preserve o registro, identifique ferramentas afetadas e planeje o reparo. Não desinstale em massa dependências do sistema desconhecidas.
O artigo original registra oito verificações com Python 3.14.0 e pip 25.2 no macOS. Um venv temporário instalou e importou um pacote de demonstração local e offline; o interpretador base e outro ambiente não conseguiram importá-lo. Ativação e chamadas por caminho direto funcionaram, e pip check passou. Os testes não reproduziram a proteção de ambiente do Ubuntu nem cobriram apt, pipx, downloads, compilação real ou serviços systemd.