Ce document est relatif à une vieille version de Python qui n'est plus soutenue. Mettez à jour votre version et lisez Bienvenue sur la documentation de la version stable actuelle de Python.

# `ensurepip` — Amorçage de l'installateur `pip`

Nouveau dans la version 3.4.

Le module `ensurepip` met en place l'installateur `pip` dans un environnement Python, classique ou virtuel. Ce principe d'amorçage a été choisi car `pip` est un projet séparé de Python avec son propre cycle de versions. Il permet en particulier d'embarquer la version la plus récente de `pip` dans les mises à jour de maintenance de l'interpréteur CPython comme dans les nouvelles versions principales.

Dans la plupart des cas, il n'est pas nécessaire de recourir à ce module. `pip` est le plus souvent déjà installé pour vous. Cependant, `ensurepip` peut s'avérer utile si l'installation de `pip` a été sautée au moment de l'installation de Python (ou en créant un environnement virtuel), ou bien si `pip` a été désinstallé par l'utilisateur.

Note

Ce module n'accède pas au réseau. Tout ce qu'il faut pour amorcer `pip` est compris dans le paquet.

Voir aussi

Installation de modules Python

  Guide de l'utilisateur final pour installer des paquets Python

PEP 453 : Amorçage explicite de pip dans les installations de Python

  Les motivations pour l'ajout de ce module et sa spécification d'origine

## Command line interface

On fait appel à l'interface en ligne de commande à l'aide de l'option `-m` de l'interpréteur.

L'invocation la plus simple est :

    python -m ensurepip

This invocation will install `pip` if it is not already installed, but otherwise does nothing. To ensure the installed version of `pip` is at least as recent as the one bundled with `ensurepip`, pass the `--upgrade` option:

    python -m ensurepip --upgrade

`pip` est installé par défaut dans l'environnement virtuel courant, s'il y en a un, ou bien dans le dossier `site-packages` du système. L'emplacement d'installation se règle à travers deux options :

- `--root <dossier>` : installe `pip` sur un chemin relatif à la racine dossier au lieu de la racine de l'environnement virtuel ou la racine par défaut de l'installation de Python.

- `--user` : installe `pip` dans le dossier `site-packages` propre à l'utilisateur au lieu du dossier global de l'installation de Python. Cette option n'est pas valide dans un environnement virtuel.

Par défaut, les commandes `pipX` et `pipX.Y` sont créées (où X.Y est la version de Python avec laquelle `ensurepip` est utilisé). Cela se contrôle par deux options supplémentaires :

- `--altinstall` : dans ce mode d'« installation parallèle », seule la commande `pipX.Y` est ajoutée, et pas la commande `pipX`.

- `--default-pip` : ce mode d'« installation de la version par défaut » crée la commande `pip` en plus de `pipX` et `pipX.Y`.

Combiner ces deux options conduit à une exception.

## API du module

Le module `ensurepip` définit deux fonctions pour utilisation dans les programmes :

`ensurepip.``version`()

  Returns a string specifying the bundled version of pip that will be installed when bootstrapping an environment.

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

  Amorce `pip` dans l'environnement courant ou un environnement spécifique.

  Passer root permet de changer la racine du chemin d'installation. Si root vaut `None` (la valeur par défaut), l'installation se fait dans la racine par défaut pour l'environnement courant.

  upgrade indicates whether or not to upgrade an existing installation of an earlier version of `pip` to the bundled version.

  Si user vaut vrai, `pip` est mis dans des chemins qui le rendent disponible pour cet utilisateur uniquement, et non pour tous les utilisateurs de l'installation de Python.

  Par défaut, les commandes créées sont `pipX` et `pipX.Y` (où X.Y est la version de Python).

  Si altinstall vaut vrai, `pipX` n'est pas créée.

  Si default_pip vaut vrai, la commande `pip` est créée en plus des deux autres.

  Le fait de combiner altinstall et default_pip lève l'exception `ValueError`.

  verbosity règle le niveau de verbosité des messages émis sur `sys.stdout` pendant l'amorçage.

  Cette fonction lève un événement d'audit `ensurepip.bootstrap` avec l'argument `root`.

  Note

  Le processus d'amorçage a des effets de bord sur `sys.path` et `os.environ`. Pour les éviter, on peut appeler l'interface en ligne de commande dans un sous-processus.

  Note

  L'amorçage peut installer des modules supplémentaires qui sont requis pour `pip`. Les autres programmes ne doivent pas prendre pour acquise la présence de ces modules, car `pip` pourrait dans une version future se passer de ces dépendances.