ensurepip --- pip インストーラーのブートストラップ

Added in version 3.4.

ソースコード: Lib/ensurepip

ensurepip パッケージは、既存の Python 環境や仮想環境に pip インストーラーをブートストラップする機能を提供します。 この方式は、pip が独自のリリース周期を持つ独立したプロジェクトであることを反映しています。 CPython 参照インタープリターのメンテナンスリリースと機能リリースには、利用可能な最新の安定版が同梱されます。

通常、pip はデフォルトでブートストラップされるため、Python のエンドユーザーがこのモジュールを直接呼び出す必要はありません。 ただし、Python のインストール時や仮想環境の作成時に pip のインストールを省略した場合や、pip を明示的にアンインストールした場合には、必要になることがあります。

注釈

このモジュールはインターネットに アクセスしません。pip のブートストラップに必要な全てはこのパッケージの一部として含まれています。

これは オプションのモジュール です。 お使いの CPython に含まれていない場合は、配布元 (Python を提供した組織や人) のドキュメントを確認してください。 配布する側の方は オプションのモジュールの要件 を参照してください。

参考

Python モジュールのインストール

エンドユーザーが Python パッケージをインストールする際のガイドです。

PEP 453: Python インストールの際の明示的なpipのブートストラッピング

このモジュールのもともとの論拠と仕様。

利用可能な環境: not Android, not iOS, not WASI.

このモジュールは モバイルプラットフォーム と WebAssemblyプラットフォーム をサポートしません。

コマンドライン・インターフェース

コマンドラインインターフェースを起動するには -m スイッチをつけてインタープリターを使用します。

最も簡単な起動方法は:

python -m ensurepip

この方法で起動すると、pip が未インストールならインストールし、インストール済みなら何もしません。 インストールされている pip を、ensurepip に同梱されたものと同じかそれより新しいバージョンにするには、--upgrade オプションを指定します。

python -m ensurepip --upgrade

デフォルトでは、pip は現在の仮想環境(もしアクティブなら)か、システムのサイトパッケージ(もしアクティブな仮想環境がなければ)にインストールされます。インストール先は２つの追加コマンドラインオプションで制御できます:

--root <dir>

現在有効な仮想環境があればそのルート、なければ現在の Python のデフォルトのルートではなく、指定されたルートディレクトリを基準に pip をインストールします。

--user

現在の Python 環境全体ではなく、ユーザーの site-packages ディレクトリに pip をインストールします (有効な仮想環境内ではこのオプションは使えません)。

デフォルトでは pipX と pipX.Y がインストールされます(X.Yは ensurepip を起動したPythonのバージョン)。インストールされるスクリプトは2つの追加コマンドラインオプションで制御できます:

--altinstall

代替インストールを指定すると、pipX スクリプトはインストール されません。

--default-pip

「デフォルトの pip」のインストールを指定すると、通常の 2 つのスクリプトに加えて pip スクリプトもインストールされます。

2つのスクリプト選択オプションを指定すると例外が発生します。

モジュール API

ensurepip には、プログラムから使うための関数が 2 つあります:

ensurepip.version()

環境にブートストラップする際にインストールされることになる利用可能な pip のバージョンを示す文字列を返します。

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

現在の環境あるいは指示された環境へ pip をブートストラップします。

root で、インストールの root ディレクトリを変更します。 root が None の場合は、インストールは現在の環境でのデフォルトの場所を使います。

upgrade で、 pip の利用可能なバージョンとして、インストール済みの以前のバージョンをアップグレードするかどうかを指定します。

user で、グローバルなインストールではなく user スキームを使うかどうかを指定します。

デフォルトではスクリプト pipX と pipX.Y はインストールされます(X.YはPythonの現在のバージョンです)。

altinstall が設定されていた場合は pipX はインストール されません。

default_pip がセットされていれば、 pip スクリプトが2つの標準スクリプトと共にインストールされます。

altinstall と default_pip の両方を指定すると、 ValueError を起こします。

verbosity でブートストラップ操作からの sys.stdout への出力の冗長レベルをコントロールします。

引数 root 付きで 監査イベント ensurepip.bootstrap を送出します。

注釈

ブートストラップ処理は sys.path, os.environ の両方に対して副作用を持ちます。代わりに、サブプロセスとしてコマンドラインインターフェイスを使うことで、これら副作用を避けることが出来ます。

注釈

ブートストラップ処理は pip によって必要とされるモジュールを追加インストールするかもしれませんが、ほかのソフトウェアはそれら依存物がいつもデフォルトで存在していることを仮定すべきではありません(将来のバージョンの pip ではその依存はなくなるかもしれませんので)。