28.2. ensurepip — Inicialização do instalador pip

Novo na versão 3.4.

O pacote ensurepip fornece suporte a fazer bootstrapping (isto é, inicializar) o instalador 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 chamar 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.

28.2.1. Interface de linha de comando

A interface da linha de comandos é 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 que acompanha o pacote 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.

    pip script will be installed in addition to the two regular scripts.

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

Alterado na versão 3.6.3: The exit status is non-zero if the command fails.

28.2.2. API do módulo

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

ensurepip.version()

Retorna uma sequência que especifica a versão em pacote 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 empacotada.

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.

Nota

O processo de inicialização tem efeitos colaterais em sys.path e os.environ. Invocar a interface da linha de comandos 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 assumir 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).