# `ensurepip` — Inicialização do instalador do `pip`

Adicionado na versão 3.4.

Código-fonte: Lib/ensurepip

The `ensurepip` package provides support for bootstrapping the `pip` installer into an existing Python installation or virtual environment. This bootstrapping approach reflects the fact that `pip` is an independent project with its own release cycle, and the latest available stable version is bundled with maintenance and feature releases of the CPython reference interpreter.

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

`ensurepip` exposes two functions for programmatic use:

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