問題說明與解決方案

在本地安裝wheeled_lab這個包的時(shí)候一直出現(xiàn)toml module找不到的錯誤，但是不管是conda的環(huán)境還是python的基本環(huán)境都已經(jīng)安裝過了toml包，后來發(fā)現(xiàn)是Python包在構(gòu)建時(shí)的構(gòu)建標(biāo)準(zhǔn)問題。

Python 包安裝系統(tǒng)正在從舊的 setup.py 方式過渡到新的 PEP 517/518 標(biāo)準(zhǔn)（使用 pyproject.toml）。

當(dāng)在ubuntu22.04運(yùn)行 pip install -e . 時(shí)，pip 會嘗試使用現(xiàn)代的 PEP 517 標(biāo)準(zhǔn)來構(gòu)建你的包。這個過程會創(chuàng)建一個臨時(shí)的、隔離的構(gòu)建環(huán)境。你的項(xiàng)目的構(gòu)建過程（即使只是為了獲取元數(shù)據(jù)）依賴于 toml 這個包（通常是 setup.py 內(nèi)部需要讀取 pyproject.toml 文件），但這個臨時(shí)的構(gòu)建環(huán)境里并沒有預(yù)裝 toml，因此導(dǎo)致了 ModuleNotFoundError，整個安裝過程就失敗了。

添加 pyproject.toml

更長期的解決方案是為你的項(xiàng)目添加一個 pyproject.toml 文件。在項(xiàng)目根目錄（wheeledlab 目錄）創(chuàng)建 pyproject.toml 文件，內(nèi)容如下：

[build-system]
requires = ["setuptools>=64.0.0", "wheel"]
build-backend = "setuptools.build_meta"

然后重新安裝：

pip install -e .

問題原因詳細(xì)解釋

這個方法很好地解決了我的問題，更詳細(xì)地解釋一下問題出現(xiàn)的原因:

pip 在構(gòu)建你的包時(shí)，并不會使用你當(dāng)前的 conda 環(huán)境 (WL)，而是創(chuàng)建了一個臨時(shí)的、隔離的“構(gòu)建環(huán)境”（Isolated Build Environment）。

詳細(xì)解釋：

1.過去的方式（你所預(yù)期的行為）

• 在舊版本的 pip 和 setuptools 中，當(dāng)你運(yùn)行 pip install 時(shí)，它會直接在你當(dāng)前激活的環(huán)境中執(zhí)行 setup.py 腳本。
• 如果 setup.py 需要某個包（比如 toml），它會期望這個包已經(jīng)存在于你的當(dāng)前環(huán)境中。
• 這就是為什么我們以前會說“請先安裝好所有構(gòu)建依賴”。

2.現(xiàn)在的方式（實(shí)際發(fā)生的情況）

• 為了解決“構(gòu)建依賴”和“運(yùn)行時(shí)依賴”混淆不清、以及構(gòu)建過程不穩(wěn)定的問題，Python 社區(qū)引入了 PEP 517 和 PEP 518 標(biāo)準(zhǔn)。

這個新標(biāo)準(zhǔn)的核心思想就是 構(gòu)建隔離 (Build Isolation)。

當(dāng)你運(yùn)行 pip install -e . 時(shí)，pip 會執(zhí)行以下步驟：

• 檢查 pyproject.toml：pip 首先會尋找 pyproject.toml 文件來獲取構(gòu)建指令。
• 創(chuàng)建隔離環(huán)境：pip 會在系統(tǒng)臨時(shí)目錄（比如 /tmp/pip-build-env-xxxx/）中創(chuàng)建一個全新的、非常迷你的虛擬環(huán)境。這個環(huán)境是完全獨(dú)立的，它不包含你 WL conda 環(huán)境中的任何包（除了最基礎(chǔ)的 Python 和 pip 本身）。

安裝構(gòu)建依賴：

• 沒有 pyproject.toml 時(shí)（你最初遇到的情況）：pip 不知道這個隔離環(huán)境需要什么額外的包。它只安裝了最基礎(chǔ)的 setuptools 和 wheel。因此，當(dāng)你的 setup.py 試圖 import toml 時(shí)，在這個“干凈”的隔離環(huán)境里找不到它，從而報(bào)錯 ModuleNotFoundError。
• 有 pyproject.toml 時(shí)（你解決后的情況）：pip 讀取了你的 pyproject.toml 文件，看到了 [build-system] 下的 requires = ["setuptools>=61.0", "toml"]。pip 于是在那個隔離的構(gòu)建環(huán)境中，首先執(zhí)行 pip install setuptools toml。
• 執(zhí)行構(gòu)建：現(xiàn)在，隔離環(huán)境里已經(jīng)有了 toml 包。pip 接著在這個準(zhǔn)備好的環(huán)境中執(zhí)行構(gòu)建后端（setuptools.build_meta），這個過程就不會再因?yàn)槿鄙?toml 而失敗了。
• 安裝項(xiàng)目：構(gòu)建成功獲取到元信息后，pip 會將你的項(xiàng)目以可編輯模式安裝回你原來的 WL` 環(huán)境。
• 清理：臨時(shí)的隔離構(gòu)建環(huán)境被刪除。

總結(jié)與類比

你可以把這個過程想象成去一個高科技實(shí)驗(yàn)室做實(shí)驗(yàn)：

• 你的 Conda 環(huán)境 (WL)：是你自己的、堆滿各種工具和材料的個人工作室。你在里面安裝了 toml。
• 隔離的構(gòu)建環(huán)境：是一個無菌操作臺（Clean Room）。你不能把你工作室里所有的東西都帶進(jìn)去，只能帶清單上列出的必需品。
• pyproject.toml：就是那張必需品清單。
• 在你沒有提供清單 (pyproject.toml) 的時(shí)候，pip 只帶了最基礎(chǔ)的工具進(jìn)入無菌操作臺。當(dāng)實(shí)驗(yàn)（構(gòu)建）需要用到 toml 這個特殊工具時(shí)，發(fā)現(xiàn)沒帶，實(shí)驗(yàn)失敗。當(dāng)你提供了清單 (pyproject.toml) 后，pip 在進(jìn)入無菌操作臺之前，先按照清單把 setuptools 和 toml 都準(zhǔn)備好了。這樣實(shí)驗(yàn)（構(gòu)建）就能順利進(jìn)行了。

所以，即使你的個人工作室 (WL 環(huán)境) 里有 toml，但無菌操作臺（隔離構(gòu)建環(huán)境）里一開始是沒有的。pyproject.toml 的作用就是告訴 pip 該往這個無菌操作臺里準(zhǔn)備些什么。

使用什么標(biāo)準(zhǔn)安裝取決于什么

那么到底是用setup.py安裝還是PEP 517/518標(biāo)準(zhǔn)安裝取決于什么呢，Ubuntu系統(tǒng)版本，Python版本，setuptools版本還是什么

在 Python 生態(tài)中，setup.py 安裝 vs. PEP 517/518 標(biāo)準(zhǔn)安裝的選擇取決于多個因素，但核心是由 pip、setuptools 版本和項(xiàng)目配置共同決定的，而不是直接由 Ubuntu 系統(tǒng)版本或 Python 版本決定。

以下是詳細(xì)分析：

1. 關(guān)鍵決定因素

2. 具體行為規(guī)則

(1) 當(dāng)項(xiàng)目有pyproject.toml時(shí)

• pip ≥19.0：強(qiáng)制使用 PEP 517/518 構(gòu)建（隔離環(huán)境）。

[build-system]
requires = ["setuptools>=61.0", "wheel"]  # 必須顯式聲明構(gòu)建依賴
build-backend = "setuptools.build_meta"   # 使用 setuptools 作為后端

• 如果缺少 toml 等依賴，會報(bào)錯（如你的案例）。
• 解決方案：在 pyproject.toml 的 requires 中添加缺失的包。

(2) 當(dāng)項(xiàng)目無pyproject.toml時(shí)

pip ≥19.0：回退到傳統(tǒng) setup.py 方式（非隔離環(huán)境）。

• 依賴主環(huán)境的包（可能引發(fā)沖突）。
• 逐步被棄用（會看到警告）。

3. 版本兼容性對照表

4. 如何強(qiáng)制選擇安裝方式？

(1) 強(qiáng)制使用傳統(tǒng)setup.py（不推薦）

pip install -e . --no-use-pep517

• 繞過 PEP 517/518，直接運(yùn)行 setup.py（可能引發(fā)其他問題）。

(2) 強(qiáng)制使用 PEP 517/518

pip install -e . --use-pep517

• 即使無 pyproject.toml 也嘗試用 PEP 517（可能失?。?/li>

5. 為什么你的案例中toml在主環(huán)境無效？

根本原因：PEP 517/518 的隔離構(gòu)建機(jī)制。

• 主環(huán)境的包（如已安裝的 toml）不會自動繼承到臨時(shí)構(gòu)建環(huán)境。
• 必須通過 pyproject.toml 的 requires 顯式聲明依賴。

6. 最佳實(shí)踐建議

始終添加 pyproject.toml

• 即使項(xiàng)目簡單，也明確聲明構(gòu)建依賴（未來兼容性）。

[build-system]
requires = ["setuptools>=64.0", "wheel"]
build-backend = "setuptools.build_meta"

升級工具鏈

python -m pip install -U pip setuptools wheel

避免混合使用新舊方式

• 不要同時(shí)依賴 setup.py 和 pyproject.toml 的隱式行為。

總結(jié)

決定性因素：pyproject.toml 存在與否 + pip/setuptools 版本。

系統(tǒng)/Python 版本：僅影響工具鏈的默認(rèn)版本，不直接決定行為。

解決方案：顯式聲明依賴（pyproject.toml）并保持工具鏈更新。

以上為個人經(jīng)驗(yàn)，希望能給大家一個參考，也希望大家多多支持腳本之家。

最新評論