ensurepip no Python: reinstale o pip

O módulo ensurepip no Python instala ou restaura o pip usando componentes já incluídos na distribuição do interpretador. Ele não acessa a internet. Seu objetivo é fazer o bootstrap do instalador quando a criação do ambiente pulou essa etapa, quando o pip foi removido ou quando uma instalação precisa recuperar uma versão mínima funcional.

Na maioria dos computadores, o usuário não precisa chamar ensurepip manualmente, pois instaladores oficiais e venv costumam fornecer pip por padrão. Distribuições Linux podem separar esse componente em outro pacote ou desativá-lo. Nesses casos, siga as instruções do fornecedor do Python em vez de forçar mudanças no ambiente do sistema.

Verificar se pip está disponível

Antes de reinstalar, confirme qual interpretador e pip estão sendo usados.

python -c "import sys; print(sys.executable)"
python -m pip --version

Prefira python -m pip ao comando pip isolado. Assim, o instalador executado pertence ao mesmo interpretador selecionado.

Bootstrap básico

O comando mais simples instala pip somente se ele ainda não estiver presente.

python -m ensurepip

A operação usa os wheels incorporados ao módulo e não baixa a versão mais recente da internet. A versão disponível depende da versão e atualização do CPython instalado.

Atualizar até a versão incorporada

Use --upgrade para garantir que o pip instalado seja pelo menos tão recente quanto a cópia fornecida por ensurepip.

python -m ensurepip --upgrade

Isso não equivale a python -m pip install --upgrade pip, que normalmente consulta um índice remoto. O bootstrap permanece offline.

Executar dentro de um ambiente virtual

Quando um venv está ativo, ensurepip instala no próprio ambiente.

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1

python -m ensurepip --upgrade
python -m pip --version

Essa é a forma mais segura para projetos. Evite alterar o Python do sistema, que pode ser gerenciado pelo sistema operacional.

Criar venv sem pip e restaurar depois

venv aceita --without-pip.

python -m venv --without-pip ambiente
ambiente/bin/python -m ensurepip

No Windows, use ambiente\Scripts\python.exe. Esse fluxo é útil para testes de bootstrap e imagens mínimas.

Instalação no diretório do usuário

A opção --user usa o esquema de site packages do usuário.

python -m ensurepip --user

Ela não é permitida dentro de um ambiente virtual ativo. Além disso, o diretório de scripts do usuário precisa estar no PATH para comandos como pip3 serem encontrados. Ainda assim, python -m pip permanece mais previsível.

Instalar sob uma raiz alternativa

--root DIR instala relativamente a uma raiz fornecida.

python -m ensurepip --root /tmp/imagem-python

Essa opção é voltada a staging, criação de imagens e empacotamento por distribuidores. Ela não transforma o diretório em ambiente virtual e pode gerar caminhos que exigem instalação posterior no local correto.

Nomes dos scripts instalados

Por padrão, ensurepip cria scripts como pipX e pipX.Y, onde X.Y corresponde à versão do Python.

--default-pip também cria o comando simples pip:

python -m ensurepip --default-pip

--altinstall evita a criação de pipX. As duas opções não podem ser usadas juntas; isso gera erro.

Evitar confusão com múltiplas versões

Em máquinas com vários Pythons, scripts globais podem apontar para ambientes diferentes.

python3.12 -m ensurepip --upgrade
python3.12 -m pip --version

No Windows, o launcher também ajuda:

py -3.12 -m ensurepip --upgrade
py -3.12 -m pip --version

Registre sempre o caminho de sys.executable em diagnósticos.

Consultar a versão incorporada

A API ensurepip.version() informa qual versão do pip está embutida.

import ensurepip

print(ensurepip.version())

Esse valor pode ser mais antigo que a versão mais recente publicada. Seu propósito é garantir um bootstrap funcional e compatível com a manutenção do CPython.

Usar bootstrap() programaticamente

import ensurepip

ensurepip.bootstrap(
    upgrade=True,
    default_pip=True,
    verbosity=1,
)

A função aceita root, upgrade, user, altinstall, default_pip e verbosity. Definir altinstall e default_pip simultaneamente gera ValueError.

Prefira subprocesso em ferramentas

A documentação informa que o bootstrap programático altera temporariamente sys.path e os.environ. Para uma ferramenta administrativa, execute a CLI em subprocesso.

import subprocess
import sys

subprocess.run(
    [sys.executable, '-m', 'ensurepip', '--upgrade'],
    check=True,
    timeout=120,
)

Isso isola efeitos, captura código de saída e reduz interferência com threads do processo principal.

O evento de auditoria

A função levanta o evento de auditoria ensurepip.bootstrap com a raiz usada. Aplicações que instalam hooks de auditoria podem observar ou bloquear a operação.

Em ambientes corporativos, registre quem solicitou o bootstrap, qual interpretador foi usado e onde os arquivos foram instalados.

ensurepip não instala qualquer pacote

O módulo instala somente pip e componentes necessários ao bootstrap. Para instalar bibliotecas do projeto, use pip depois.

python -m ensurepip --upgrade
python -m pip install -r requirements.txt

O guia sobre instalação de bibliotecas com pip aborda requirements, versões e ambientes virtuais.

Não dependa das dependências internas do pip

O bootstrap pode instalar módulos usados pelo pip, mas a documentação alerta que outros programas não devem pressupor que eles sempre estarão presentes. Dependências internas podem mudar ou ser vendorizadas de outra forma.

Declare explicitamente tudo que sua aplicação importa.

Disponibilidade opcional

Ensurepip é opcional em builds de CPython. Ele não está disponível em Android, iOS e WASI. Algumas distribuições Linux também o removem ou o empacotam separadamente.

Se python -m ensurepip informa que o módulo não existe, procure o pacote oficial da distribuição, como o componente de venv ou pip correspondente. Não copie arquivos aleatórios de outra instalação.

Python gerenciado pelo sistema

Sistemas modernos podem marcar o ambiente global como externamente gerenciado. Mesmo que ensurepip esteja presente, instalar ou atualizar pacotes globais pode quebrar ferramentas do sistema.

Crie um venv:

python -m venv .venv
.venv/bin/python -m pip install pacote

Para aplicativos de linha de comando, ferramentas como pipx podem oferecer isolamento adequado.

Permissões

Um erro de permissão normalmente indica que você está tentando gravar no Python global. Não resolva automaticamente com sudo pip.

Confirme o destino, use um venv ou o esquema de usuário. Em servidores, construa o ambiente durante o deploy com um usuário dedicado.

Ambientes offline

Ensurepip funciona offline porque seus componentes vêm junto ao Python. Depois do bootstrap, instalar outras dependências ainda exige wheels locais ou um índice interno.

python -m pip install \
  --no-index \
  --find-links /opt/wheels \
  -r requirements.txt

Verifique hashes e origem dos wheels. Offline não significa automaticamente confiável.

Containers

Em imagens de container, use ensurepip apenas quando o Python base não fornece pip e você realmente precisa dele no estágio de build.

Evite manter caches e ferramentas de compilação desnecessárias na imagem final. Builds multi-stage podem instalar dependências em um estágio separado.

Diagnosticar pip quebrado

Primeiro confirme que o módulo pip é importável.

python -c "import pip; print(pip.__version__)"

Se o import falha, tente ensurepip dentro de um venv novo. Se o venv novo funciona, o problema provavelmente está no ambiente antigo. Recriar o ambiente costuma ser mais seguro que reparar arquivos manualmente.

Recriar em vez de reparar

Ambientes virtuais devem ser reproduzíveis a partir de arquivos de dependência. Quando estão corrompidos:

rm -rf .venv
python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

No Windows, remova a pasta por ferramentas apropriadas. Não versione o diretório do venv.

Integração com importlib.metadata

Depois do bootstrap, importlib.metadata no Python pode confirmar a versão instalada.

from importlib.metadata import version

print(version('pip'))

Isso consulta a distribuição, enquanto ensurepip.version() consulta a versão disponível para bootstrap. Os valores podem diferir.

Testar automações

Não teste bootstrap no Python global da máquina. Crie um venv temporário e invoque seu interpretador.

import subprocess
import sys

subprocess.run(
    [sys.executable, '-m', 'venv', '--without-pip', 'tmp-venv'],
    check=True,
)
subprocess.run(
    ['tmp-venv/bin/python', '-m', 'ensurepip'],
    check=True,
)

Adapte o caminho no Windows e limpe o diretório depois. Teste também ausência do módulo em plataformas opcionais.

Erros frequentes

• Usar ensurepip para buscar o pip mais recente.
• Confundir pip global com pip do venv.
• Executar bootstrap programático em processo multithread.
• Combinar --altinstall e --default-pip.
• Forçar instalação no Python do sistema.
• Presumir disponibilidade em qualquer plataforma.
• Depender dos módulos internos instalados com pip.

Boas práticas

• Use python -m pip.
• Prefira ambientes virtuais.
• Use subprocesso para isolamento.
• Confirme sys.executable e destino.
• Respeite políticas da distribuição.
• Recrie venvs corrompidos.
• Fixe e verifique dependências posteriores.

Conclusão

O ensurepip no Python fornece uma forma offline e previsível de instalar ou restaurar o pip incorporado ao CPython. Ele é especialmente útil em ambientes virtuais criados sem pip e em diagnósticos controlados.

Evite modificar o Python do sistema e não confunda bootstrap com atualização online. Consulte a documentação oficial do ensurepip e o guia da PyPA para instalar pacotes.