# `ensurepip` --- `pip` 安裝器的初始建置 (bootstrapping)

在 3.4 版被加入.

原始碼： Lib/ensurepip

`ensurepip` 套件 (package) 為既有的 Python 安裝或虛擬環境提供 `pip` 安裝器初始建置 (bootstrapping) 的支援。這個初始建置的方式應證了事實 —— `pip` 是有其獨立發布週期的專案，且其最新可用穩定的版本，會與 CPython 直譯器 (interpreter) 之維護和功能發布綁定。

大多數情況下，Python 的終端使用者不需要直接調用此模組（因為 `pip` 預設應為初始建置），但若安裝 Python 時 `pip` 被省略（或建立一虛擬環境時），又或是 `pip` 被明確解除安裝時，則此模組的初始建置仍有可能用上。

備註

此模組不會通過網路存取。所有需要用來初始建置 `pip` 的元件都已包含在套件之內。

也參考

安裝 Python 模組

  對於終端使用者安裝 Python 套件的指引

PEP 453: 在 Python 安裝中的 pip 明確初始建置

  此模組的最初設計理念與規範。

適用：非 Android、非 iOS、非 WASI。

此模組在行動平台或WebAssembly 平台上不支援。

## 命令列介面

使用直譯器 (interpreter) 的 `-m` 來調用命令列介面

最簡單可行的調用：

    python -m ensurepip

若 `pip` 未安裝，此調用會將其安裝；否則甚麼也不做。可透過傳入 `--upgrade` 參數來確保 `pip` 的安裝版本至少為當前 `ensurepip` 中最新可用的版本：

    python -m ensurepip --upgrade

預設上，`pip` 會被安裝至當前虛擬環境（若已啟動虛擬環境）或系統端的套件（若沒有啟動的虛擬環境）。安裝位置可透過兩個額外的命令列選項來控制：

- `--root <dir>`：安裝 `pip` 到給定的根目錄 (root directory) 的相對路徑，而不是當前虛擬環境（若存在）的根目錄，或當前 Python 安裝版所預設的根目錄。

- `--user` ：安裝 `pip` 到使用者端的套件目錄，而不是全域安裝到當前的 Python 安裝版（此選項不允許在一啟動的虛擬環境中使用）。

預設會安裝 `pipX` 和 `pipX.Y` 腳本（X.Y 代表用來調用 `ensurepip` 的 Python 之版本）。安裝的腳本可透過兩個額外的命令列選項來控制：

- `--altinstall`：若要求一個替代安裝版，則不會安裝 `pipX` 腳本。

- `--default-pip`： 若要求安裝「預設 pip」，則會安裝 `pip` 腳本，及 2 個常規腳本。

提供兩種指令選項將會導致例外 (exception) 。

## 模組 API

`ensurepip` 開放了兩個用於編寫程式的函式：

ensurepip.version()

  回傳一個字串，用以標明初始建置時，安裝的 pip 的可行版本號。

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

  在當前或指定的環境之中建立 `pip`。

  root 指定一個替代的根目錄，作為安裝的相對路徑。若 root 為 `None`，則安裝使用當前環境的預設安裝位置。

  upgrade 指出是否要將一個既有的較早版本的 `pip` 升級至可用的新版。

  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` 均有副作用。改為在一子行程 (subprocess) 調用命令列介面可避免這些副作用。

  備註

  初始建置的過程也許會安裝 `pip` 所需要的額外的模組，但其他軟體不應該假設這些相依 (dependency) 總是預設存在（因為這些相依很可能會在未來版本的 `pip` 中被移除）。