建置系統介面

在處理套件的可安裝原始碼發行版時，pip 沒有直接處理該套件的建置處理程序。這項職責委派給「建置後端」，也稱為「建置系統」。這意謂 pip 需要一個介面，才能與這些建置後端互動。

pip 使用兩個主要介面來進行這些互動

pyproject.toml 為基礎

受標準支援的介面，具有明確的宣告和建置相依性的管理。

setup.py 為基礎

舊版介面，我們正努力讓使用者不再使用它。沒有良好機制來宣告建置相依性。

各個介面的詳細資訊可以在其專用頁面中找到，如上所述連結。本文件涵蓋 pip 將為專案使用的建置系統介面周圍的細微差別，以及適用於 pip 可能使用的所有建置系統介面的詳細資訊。

判斷使用哪個建置系統介面

目前，如果存在 pyproject.toml 檔案，pip 則會使用 pyproject.toml 為基礎的建置系統介面。否則，則會使用舊版建置系統介面。我們的目標是無條件地切換到使用 pyproject.toml 建置系統介面，並在未來的某個時間點停止支援舊版建置系統介面。

執行建置時，pip 會提及它正在使用的建置系統介面。通常會以如下訊息的形式呈現

Building wheel for pip (pyproject.toml)... done

Building wheel for pip (setup.py)... done

括弧中的內容，是指使用哪個建置系統介面。

在第 21.3 版中變更： 輸出使用「pyproject.toml」而非「PEP 517」來指稱為 pyproject.toml 為基礎的建置系統介面。

控制使用哪個建置系統介面

旗標 --use-pep517（和對應環境變數：PIP_USE_PEP517）可以用來強制所有套件使用 pyproject.toml 為基礎的建置系統介面來建置。沒有辦法強制使用舊版建置系統介面。

控制 setup_requires

提示

這只適用於將 setuptools 用作建置後端且在 setup.py 檔案中使用 setup_requires 關鍵字引數的專案。

setup.py 中的 setup_requires 引數用於指定套件的建置時間相依性。這已被 pyproject.toml 檔案中的 build-system.requires 鍵所取代（根據 PEP 518）。不過，有時會遇到使用 setup_requires 的套件（例如：套件尚未更新為使用更新方法！）

如果您控制該套件，請考慮加入 pyproject.toml 檔案以使用現代建置系統介面。如此一來，即可避免透過委派 pip 進行安裝來觸發有問題的行為。

對於終端使用者而言，處理具備 setup_requires 的套件時，最好的解決方案事先安裝 setup_requires 中列出的套件，使用先前的 pip install 指令。這是因為無法控制 easy_install 如何找到這些相依性，或 setuptools 將如何使用 pip 的指令列選項呼叫 pip，這使得以適當的方式運作變得困難。

如果您要確保 easy_install 呼叫不會接觸 PyPI，您需要使用 distutils 組態檔來組態其行為。以下是一些範例

  • 讓相依性位於 easy_install 的備用索引中

    [easy_install]
index_url = https://my.index-mirror.com

  • 讓相依性從本機目錄中找到，而非爬取 PyPI，新增這個

    [easy_install]
allow_hosts = ''
find_links = file:///path/to/local/archives/

歷史背景

setuptools < 52.0 將使用 easy_install 嘗試滿足 setup_requires 相依性，這可能導致奇怪的失敗 -- easy_install 無法理解許多現代 Python 封裝標準，而且通常會嘗試安裝不相容的套件版本或不正確地建置套件。它也會產生不適當的指令碼包裝，在許多情況下無法正常運作。

setuptools 的較新版本會使用 pip 進行這些安裝，但僅能傳遞有限的命令列引數。這也可能會導致奇怪的錯誤和細微不正確的行為。