問題說明與解決方案

在本地安裝wheeled_lab這個(gè)包的時(shí)候一直出現(xiàn)toml module找不到的錯(cuò)誤，但是不管是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 會(huì)嘗試使用現(xiàn)代的 PEP 517 標(biāo)準(zhǔn)來構(gòu)建你的包。這個(gè)過程會(huì)創(chuàng)建一個(gè)臨時(shí)的、隔離的構(gòu)建環(huán)境。你的項(xiàng)目的構(gòu)建過程（即使只是為了獲取元數(shù)據(jù)）依賴于 toml 這個(gè)包（通常是 setup.py 內(nèi)部需要讀取 pyproject.toml 文件），但這個(gè)臨時(shí)的構(gòu)建環(huán)境里并沒有預(yù)裝 toml，因此導(dǎo)致了 ModuleNotFoundError，整個(gè)安裝過程就失敗了。

添加 pyproject.toml

更長期的解決方案是為你的項(xiàng)目添加一個(gè) 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ì)解釋

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

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

詳細(xì)解釋：

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

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

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

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

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

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

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

總結(jié)與類比

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

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

所以，即使你的個(gè)人工作室 (WL 環(huán)境) 里有 toml，但無菌操作臺(tái)（隔離構(gòu)建環(huán)境）里一開始是沒有的。pyproject.toml 的作用就是告訴 pip 該往這個(gè)無菌操作臺(tái)里準(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)安裝的選擇取決于多個(gè)因素，但核心是由 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 等依賴，會(huì)報(bào)錯(cuò)（如你的案例）。
• 解決方案：在 pyproject.toml 的 requires 中添加缺失的包。

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

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

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

3. 版本兼容性對(duì)照表

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）不會(huì)自動(dòng)繼承到臨時(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"

升級(jí)工具鏈

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）并保持工具鏈更新。

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