# `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.

Este é um módulo opcional. Se ele estiver faltando na sua cópia do CPython, procure a documentação do seu distribuidor (ou seja, quem lhe forneceu o Python). Se você for o distribuidor, consulte Requisitos para módulos opcionais.

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.

Disponibilidade: 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`).