ensurepip — Inicialização do instalador do pip

Adicionado na versão 3.4.

Código-fonte: Lib/ensurepip

O pacote ensurepip fornece suporte a fazer bootstrapping, ou seja, inicializar o instalador do pip em uma instalação existente do Python ou em um ambiente virtual. Essa abordagem de bootstrapping reflete o fato de que pip é um projeto independente com seu próprio ciclo de lançamento, e a última versão estável disponível é fornecida com manutenção e lançamentos de recursos do interpretador de referência CPython.

Na maioria dos casos, os usuários finais do Python não precisam invocar esse módulo diretamente (como pip deve ser inicializado por padrão), mas pode ser necessário se a instalação do pip foi ignorada ao instalar o Python (ou ao criar um ambiente virtual) ou após desinstalar explicitamente pip.

Nota

Este módulo não acessa a Internet. Todos os componentes necessários para iniciar o pip estão incluídos como partes internas do pacote.

Ver também

Instalando módulos Python

O guia do usuário final para instalar pacotes Python

PEP 453: Inicialização explícita de pip em instalações Python

A justificativa e especificação originais para este módulo.

Availability: not Android, not iOS, not WASI.

Este módulo não tem suporte em plataformas móveis ou plataformas WebAssembly.

Interface de linha de comando

A interface da linha de comando é chamada usando a opção -m do interpretador.

A invocação mais simples possível é:

python -m ensurepip

Essa invocação instalará pip se ainda não estiver instalada, mas, caso contrário, não fará nada. Para garantir que a versão instalada do pip seja pelo menos tão recente quanto a disponível do ensurepip, passe a opção --upgrade:

python -m ensurepip --upgrade

Por padrão, pip é instalado no ambiente virtual atual (se houver um ativo) ou nos pacotes de sites do sistema (se não houver um ambiente virtual ativo). O local da instalação pode ser controlado através de duas opções adicionais de linha de comando:

  • --root dir: Instala pip em relação ao diretório raiz fornecido, em vez da raiz do ambiente virtual atualmente ativo (se houver) ou a raiz padrão da instalação atual do Python.

  • --user: Instala pip no diretório de pacotes do site do usuário em vez de globalmente para a instalação atual do Python (essa opção não é permitida dentro de um ambiente virtual ativo).

Por padrão, os scripts pipX e pipX.Y serão instalados (onde X.Y representa a versão do Python usada para invocar ensurepip). Os scripts instalados podem ser controlados através de duas opções adicionais de linha de comando:

  • --altinstall: se uma instalação alternativa for solicitada, o script pipX não será instalado.

  • --default-pip: se uma instalação “pip padrão” for solicitada, o script pip será instalado junto com os dois scripts comuns.

Fornecer as duas opções de seleção de script acionará uma exceção.

API do módulo

O ensurepip expõe duas funções para uso programático:

ensurepip.version()

Retorna uma string que especifica a versão disponível do pip que será instalado ao inicializar um ambiente.

ensurepip.bootstrap(root=None, upgrade=False, user=False, altinstall=False, default_pip=False, verbosity=0)

Inicializa pip no ambiente atual ou designado.

root especifica um diretório raiz alternativo para instalar em relação a. Se root for None, a instalação utilizará o local de instalação padrão para o ambiente atual.

upgrade indica se deve ou não atualizar uma instalação existente de uma versão anterior do pip para a versão disponível.

user indica se é necessário usar o esquema do usuário em vez de instalar globalmente.

Por padrão, os scripts pipX e pipX.Y serão instalados (onde X.Y significa a versão atual do Python).

Se altinstall estiver definido, o pipX não será instalado.

Se default_pip estiver definido, o pip será instalado além dos dois scripts comuns.

Definir altinstall e default_pip acionará ValueError.

verbosity controla o nível de saída para sys.stdout da operação de inicialização.

Levanta um evento de auditoria ensurepip.bootstrap com o argumento root.

Nota

O processo de inicialização tem efeitos colaterais em sys.path e os.environ. Invocar a interface da linha de comando em um subprocesso permite que esses efeitos colaterais sejam evitados.

Nota

O processo de inicialização pode instalar módulos adicionais exigidos pelo pip, mas outro software não deve presumir que essas dependências sempre estarão presentes por padrão (como as dependências podem ser removidas em uma versão futura do pip).