pip install¶

用法¶

Unix/macOS

python -m pip install [options] <requirement specifier> [package-index-options] ...
python -m pip install [options] -r <requirements file> [package-index-options] ...
python -m pip install [options] [-e] <vcs project url> ...
python -m pip install [options] [-e] <local project path> ...
python -m pip install [options] <archive url/path> ...

Windows

py -m pip install [options] <requirement specifier> [package-index-options] ...
py -m pip install [options] -r <requirements file> [package-index-options] ...
py -m pip install [options] [-e] <vcs project url> ...
py -m pip install [options] [-e] <local project path> ...
py -m pip install [options] <archive url/path> ...

說明¶

從以下是安裝套件

PyPI（及其他索引）使用需求規格。
VCS 專案網址。
本機專案目錄。
本機或遠端來源檔案。

pip 也支援從「需求檔案」內安裝，是一種指定要安裝的整體環境的簡易方式。

概觀¶

pip install 具有多個階段

識別基本需求。在此處理使用者提供的參數。
解決相依關係。在此決定要安裝什麼。
建置輪組。可建置輪組的所有相依關係都在此建置。
安裝套件（並解除安裝任何正在升級/取代的項目）。

請注意 pip install 會偏好維持已安裝版本，除非指定 --upgrade。

參數處理¶

檢視待安裝項目時，pip 會按以下順序檢查每項項目的類型

專案或檔案網址。
本機目錄（其中必須含有 pyproject.toml 或 setup.py，否則 pip 會回報錯誤）。
本機檔案（依據這些格式的命名慣例追蹤的 sdist 或輪組格式檔案）。
版本規格。

每項識別出的項目都新增到要由安裝滿足的需求集合中。

找出名稱和版本¶

對於每一個候選項目，pip 需要知道專案名稱和版本。對於輪組（由 .whl 檔案副檔名識別）可由檔名取得，依循輪組規範。對於本機目錄或明確指定的 sdist 檔案，會使用 setup.py egg_info 指令來決定專案元資料。對於透過索引找到的 sdist，會剖析檔名以取得名稱和專案版本（理論上會比使用 egg_info 指令稍不那麼可靠，但可避免下載和處理不必要的眾多檔案）。

任何網址都可使用 #egg=name 語法（請參閱 VCS 支援）明確陳述專案名稱。

滿足需求¶

一旦 pip 獲得了一組需求來滿足，它會使用下列簡單規則來選擇要安裝每個需求的哪個版本：將會安裝符合給定約束的最新版本（但對於前置版本例外，請參閱這裡）。當所選版本的來源不只一個時，會假設每個來源都是可接受的（否則版本會不同）。

取得已安裝內容的資訊¶

安裝指令有 --report 選項，這會產生 pip 所安裝內容的 JSON 報告。配合 --dry-run 和 --ignore-installed 使用時，用來解決一組需求而不實際安裝它們。

報告可以寫到檔案，也可以寫到標準輸出（搭配 --quiet 使用 --report -）。

JSON 報告的格式說明在安裝報告中。

安裝順序¶

備註

此部分只針對執行時間相依性的安裝順序，不適用於建構相依性（那些使用 [建構系統] 表格指定）。

從 v6.1.0 開始，pip 會在相依性之前安裝它們的依賴項，也就是「拓撲順序」。這是 pip 目前對順序所做的唯一保證。儘管 PIP 可能巧合地按照安裝參數順序或 requirement 檔案中項目的順序來安裝，這並非一種保證。

在相依循環（又稱「循環相依性」）情況下，目前的執行（未來可能變更）會讓迴圈中首先遇到的成員最後安裝。

例如，如果 quux 仰賴 foo，foo 仰賴 bar，bar 仰賴 baz，而 baz 仰賴 foo

Unix/macOS

$ python -m pip install quux
...
Installing collected packages baz, bar, foo, quux

$ python -m pip install bar
...
Installing collected packages foo, baz, bar

Windows

C:\> py -m pip install quux
...
Installing collected packages baz, bar, foo, quux

C:\> py -m pip install bar
...
Installing collected packages foo, baz, bar

在 v6.1.0 之前，pip 未對安裝順序做出任何保證。

決定以拓撲順序安裝是基於在每個步驟中都讓環境保持可用的安裝原則。這有兩個主要的實際優點

在安裝期間並行使用環境更有可能順利進行。
失敗的安裝較不容易造成損壞的環境。儘管 pip 預計最終將支援故障回退，但目前這是一個改進。

雖然新的安裝順序並非旨在取代（也未取代）使用 setup_requires 宣告建置相依項目，但它可能有助於某些專案從 sdist（早期可能失敗）安裝，而這些專案符合下列特徵

它們具有建置相依項目，也使用 install_requires 宣告為安裝相依項目。
python setup.py egg_info 在未安裝其建置相依項目下運作。
由於某種原因，它們並未或不會使用 setup_requires 宣告其建置相依項目。

需求檔案格式

本節已移至需求檔案格式。

需求規範

本節已移至需求規格。

每個需求的覆寫

這部分現在納入需求檔案格式中。

預先發布版本¶

從 v1.4 開始，pip 預設僅會安裝如預先發行所指定的穩定版本。如果無法解析版本為相容的版本，則假設它是預先發行版本。

如果需求規格包括預先發行或開發版本（例如 >=0.0.dev0），pip 將允許該需求的預先發行和開發版本。這不包含 != 旗標。

pip install 命令也支援 --pre 旗標，可啟用安裝預先發行和開發版本。

VCS 支援

這部分現在納入 VCS 支援中。

尋找套件¶

pip 使用 PyPI 上的 HTTP 簡化介面尋找套件，其文件記載於這裡和這裡。

pip 提供多個套件索引選項，可變更尋找套件的方式。

pip 在許多地方尋找套件：PyPI (或透過 --index-url 指定的索引，如果未透過 --no-index 停用)，在本地檔案系統，以及透過 --find-links 或 --extra-index-url 指定的任何其他存放區。要搜尋的位置沒有優先順序。而是檢查所有位置，然後選取最符合需求的結果 (根據版本號碼，請參閱規格以取得詳細資料)。

請參閱 pip 安裝範例。

SSL 憑證驗證

這現已涵蓋在 HTTPS 憑證中。

快取

這現已涵蓋在快取中。

輪快取

這現已涵蓋在快取中。

雜湊檢查模式

這現已涵蓋在安全安裝中。

本地專案安裝

這現已涵蓋在本地專案安裝中。

可編輯安裝

這現已涵蓋在本地專案安裝中。

建置系統介面

這現已涵蓋在建置系統介面中。

選項¶

-r, --requirement <檔名>¶

從給定的需求檔案安裝。此選項可使用多次。

(環境變數：PIP_REQUIREMENT)

-c, --constraint <檔名>¶

使用給定的限制檔案限制版本。此選項可使用多次。

(環境變數：PIP_CONSTRAINT)

--no-deps¶

不要安裝套件相依性。

(環境變數：PIP_NO_DEPS，PIP_NO_DEPENDENCIES)

--pre¶

包含預發佈和開發版本。預設情況下，pip 只會找到穩定版本。

(環境變數：PIP_PRE)

-e, --editable <path/url>¶

從本機專案路徑或版本控制系統網址，以可編輯模式（即 setuptools“開發模式”）安裝專案。

(環境變數：PIP_EDITABLE)

--dry-run¶

實際上不會安裝任何東西，只會列印將會安裝的內容。可與 --ignore-installed 搭配使用，以“解析”需求。

(環境變數：PIP_DRY_RUN)

-t, --target <dir>¶

將套件安裝到 <dir>。預設情況下，此方法不會取代 <dir> 中現有的檔案或資料夾。使用 --upgrade 可以用新版本取代 <dir> 中現有的套件。

(環境變數：PIP_TARGET)

--platform <platform>¶

只使用與 <platform> 相容的輪件。預設為執行系統的平台。使用此選項多次，指定目標直譯器支援的各種平台。

(環境變數：PIP_PLATFORM)

--python-version <python_version>¶

Python 直譯器版本，適用於輪件與“Requires-Python”相容性檢查。預設值衍生自執行直譯器。版本可用最多三個以點分隔的整數指定（例如“3”代表 3.0.0，“3.7”代表 3.7.0，或“3.7.3”）。主次版本也可表示為沒有點號的字串（例如“37”代表 3.7.0）。

(環境變數：PIP_PYTHON_VERSION)

--implementation <implementation>¶

僅使用與 Python 實作 <實作> 相容的輪件，例如「pp」、「jy」、「cp」或「ip」。如果未指定，則使用目前的詮釋器實作。使用「py」來強制使用與實作無關的輪件。

(環境變數：PIP_IMPLEMENTATION)

--abi <abi>¶

僅使用與 Python abi <abi> 相容的輪件，例如「pypy_41」。如果未指定，則使用目前的詮釋器 abi 標籤。重複使用這個選項以指定目標詮釋器支援的多個 abi。通常，在使用這個選項時，您需要指定 --implementation、--platform 和 --python-version。

(環境變數：PIP_ABI)

--user¶

安裝到平台的 Python 使用者安裝目錄。通常為 ~/.local/，Windows 上則為 %APPDATA%Python。（請參閱 Python 文件 site.USER_BASE 以取得完整詳細資訊。）

(環境變數：PIP_USER)

--root <dir>¶

相對於這個另類根目錄安裝全部內容。

(環境變數：PIP_ROOT)

--prefix <dir>¶

安裝前綴，其中包含 lib、bin 和其他頂層資料夾。請注意，產生的安裝可能包含腳本和其他參考 pip 而不是 --prefix 的 Python 詮釋器的資源。如果您打算將套件安裝到其他（可能為 pip 免費）環境，請參閱 --python 選項。

(環境變數：PIP_PREFIX)

--src <dir>¶

檢出可編輯專案的目錄。在虛擬環境中的預設值為「<venv 路徑>/src」。全球安裝的預設值為「<目前目錄>/src」。

(環境變數：PIP_SRC、PIP_SOURCE、PIP_SOURCE_DIR、PIP_SOURCE_DIRECTORY)

-U, --upgrade¶

將所有指定 package 升級至最新版本。處理相依性會根據所使用的升級策略而定。

(環境變數：PIP_UPGRADE)

--upgrade-strategy <upgrade_strategy>¶

決定如何處理相依性升級 [預設值：only-if-needed]。「eager」 - 不論目前已安裝的版本是否滿足已升級 package 的需求，相依性都會升級。「only-if-needed」 - 僅在未滿足已升級 package 的需求時，才會升級。

(環境變數：PIP_UPGRADE_STRATEGY)

--force-reinstall¶

重新安裝所有 package，即使它們已為最新版本。

(環境變數：PIP_FORCE_REINSTALL)

-I, --ignore-installed¶

忽略已安裝 package 並覆寫它們。如果現有 package 是不同版本，或是使用不同套件管理員安裝的，這可能會損毀您的系統！

(環境變數：PIP_IGNORE_INSTALLED)

--ignore-requires-python¶

忽略 Requires-Python 資訊。

(環境變數：PIP_IGNORE_REQUIRES_PYTHON)

--no-build-isolation¶

在建置新式來源 distribution 期間停用孤立。如果使用這個選項，則必須已經安裝 PEP 518 中指定的建置相依性。

(環境變數：PIP_NO_BUILD_ISOLATION)

--use-pep517¶

使用 PEP 517 建置來源 distribution（使用 --no-use-pep517 強制套用傳統行為）。

(環境變數：PIP_USE_PEP517)

--check-build-dependencies¶

當使用 PEP517 時，檢查建立的相依性。

(環境變數：PIP_CHECK_BUILD_DEPENDENCIES)

--break-system-packages¶

允許 pip 修改外部管理的 Python 安裝

(環境變數：PIP_BREAK_SYSTEM_PACKAGES)

-C, --config-settings <settings>¶

要傳遞給 PEP 517 建立後端的組態設定。設定的格式為 KEY=VALUE。請使用多個 --config-settings 選項，才能傳遞多個金鑰給後端。

(環境變數：PIP_CONFIG_SETTINGS)

--global-option <options>¶

在安裝或 bdist_wheel 命令之前，要提供的額外全域選項，供 setup.py 呼叫。

(環境變數：PIP_GLOBAL_OPTION)

--compile¶

將 Python 原始碼檔案編譯成位元組碼

(環境變數：PIP_COMPILE)

--no-compile¶

不將 Python 原始碼檔案編譯成位元組碼

(環境變數：PIP_NO_COMPILE)

--no-warn-script-location¶

在 PATH 外部安裝指令碼時，不發出警告訊息

(環境變數：PIP_NO_WARN_SCRIPT_LOCATION)

--no-warn-conflicts¶

對損壞的相依性，不發出警告訊息

(環境變數：PIP_NO_WARN_CONFLICTS)

--no-binary <格式控制>¶

不使用二進制套件。可多次提供，每次都會加到現有的值。可接受 “:all:” 來停用所有二進制套件，或 “:none:” 來清空設定（注意冒號），或一個或多個套件名稱，用逗號分隔（沒有冒號）。請注意，某些套件難以編譯，使用此選項後可能無法安裝。

(環境變數： PIP_NO_BINARY)

--only-binary <格式控制>¶

不使用原始碼套件。可多次提供，每次都會加到現有的值。可接受 “:all:” 來停用所有原始碼套件，或 “:none:” 來清空設定，或一個或多個套件名稱，用逗號分隔。沒有二進制套件的套件會在使用此選項時無法安裝。

(環境變數： PIP_ONLY_BINARY)

--prefer-binary¶

優先使用二進制套件而非原始碼套件，即使原始碼套件較新。

(環境變數： PIP_PREFER_BINARY)

--require-hashes¶

要求一個雜湊函數來檢查每個需求，以進行重複安裝。此選項在需求檔案中任何套件都有 --hash 選項時會被隱含。

(環境變數： PIP_REQUIRE_HASHES)

--progress-bar <進度條>¶

指定是否應使用進度條 [on、off、raw]（預設：on）

(環境變數： PIP_PROGRESS_BAR)

--root-user-action <root 使用者動作>¶

如果 pip 以 root 使用者執行，則採取的動作 [warn、ignore]（預設：warn）

(環境變數： PIP_ROOT_USER_ACTION)

--report <檔案>¶

產生 JSON 檔，說明 pip 安裝提供的需求時執行哪些動作。可與 --dry-run 和 --ignore-installed 搭配使用來「解析」需求。當 - 用作檔名時，就會寫入至 stdout。在寫入 stdout 時，請結合 --quiet 選項，避免將 pip 記錄輸出與 JSON 輸出混在一起。

(環境變數：PIP_REPORT)

--no-clean¶

不清除建置目錄。

(環境變數：PIP_NO_CLEAN)

-i, --index-url <網址>¶

Python 套件索引的基本網址（預設為 https://pypi.org/simple）。這應該指向與 PEP 503（簡單的儲存庫 API）相容的儲存庫，或採用相同格式設定的本機目錄。

(環境變數：PIP_INDEX_URL, PIP_PYPI_URL)

--extra-index-url <網址>¶

額外的套件索引網址，可搭配 --index-url 使用。應遵循與 --index-url 相同的規則。

(環境變數：PIP_EXTRA_INDEX_URL)

--no-index¶

略過套件索引（改為僅查看 --find-links 網址）。

(環境變數：PIP_NO_INDEX)

-f, --find-links <網址>¶

如果是指向 html 檔的網址或路徑，則分析連結至封存檔的連結，例如 sdist (.tar.gz) 或 wheel (.whl) 檔。如果是本機路徑或 file:// URL（目錄），則在目錄清單中尋找封存檔。VCS 專案網址的連結不受支援。

(環境變數：PIP_FIND_LINKS)

pip install¶

用法¶

說明¶

概觀¶

參數處理¶

找出名稱和版本¶

滿足需求¶

取得已安裝內容的資訊¶

安裝順序¶

預先發布版本¶

尋找套件¶

選項¶

範例¶