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

在 3.4 版被加入.

原始碼：Lib/ensurepip

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

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

備註

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

This is an optional module. If it is missing from your copy of CPython, look for documentation from your distributor (that is, whoever provided Python to you). If you are the distributor, see 可選模組的需求.

也參考

安裝 Python 模組

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

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

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

可用性: not Android, not iOS, not 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` 中被移除）。