This document is for an old version of Python that is no longer supported. You should upgrade and read the documentação do Python para versão estável atual.

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

Novo na versão 2.7.9.

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.

PEP 477: Backport ensurepip (PEP 453) to Python 2.7

  The rationale and specification for backporting PEP 453 to Python 2.7.

## 27.2.1. 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 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).

By default, the scripts `pip`, `pipX`, and `pipX.Y` will be installed (where X.Y stands for the version of Python used to invoke `ensurepip`). The scripts installed can be controlled through two additional command line options:

- `--altinstall`: if an alternate installation is requested, the `pip` and `pipX` script will not be installed.

- `--no-default-pip`: if a non-default installation is request, the `pip` script will not be installed.

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

## 27.2.2. 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 em pacote do pip que será instalado ao inicializar um ambiente.

`ensurepip.``bootstrap`(root=None, upgrade=False, user=False, altinstall=False, default_pip=True, 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.

  By default, the scripts `pip`, `pipX`, and `pipX.Y` will be installed (where X.Y stands for the current version of Python).

  If altinstall is set, then `pip` and `pipX` will not be installed.

  If default_pip is set to `False`, then `pip` will not be installed.

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