Python系列Bug修復PyCharm控制枱pip install報錯：如何解決 pip install -r requirements.txt 子目錄可編輯安裝缺少 pyproject.toml 問題

摘要

在日常使用 PyCharm 進行 Python 開發時，我們經常會在執行 pip install 或 pip install -r requirements.txt 時遇到各種詭異的安裝錯誤。
尤其是在新版 Python 3.12+ 與 pip 24+ 環境下，子目錄可編輯安裝缺少 pyproject.toml 這個錯誤成為開發者的噩夢。

本文將以真實開發環境為例，深入剖析此問題產生的根源，並提供多個可行的解決思路與配置優化方案，助你徹底解決該類報錯。

文章目錄

• Python系列Bug修復PyCharm控制枱pip install報錯：如何解決 pip install -r requirements.txt 子目錄可編輯安裝缺少 pyproject.toml 問題

• 摘要
• 一、開發環境説明
• 二、問題場景重現

• 報錯含義解析

• 三、問題分析思路
• 四、常見原因與解決方案

• 1️⃣ module 包未安裝或包名錯誤
• 2️⃣ 網絡問題，切換國內源鏡像
• 3️⃣ 沒有 `__init__.py` 文件
• 4️⃣ 包版本不匹配
• 5️⃣ 自定義包名衝突
• 6️⃣ PYTHONPATH 未正確設置
• 7️⃣ 相對導入錯誤
• 8️⃣ pip 版本過舊

• 五、深度進階方案

• 使用 pyproject.toml 規範項目結構
• 使用 PEP 660 支持可編輯安裝

• 六、問題排查總結表
• 七、更多進階技巧
• 八、數學原理小插曲（LaTeX演示）
• 九、結語與延伸閲讀
• ✍️ 作者名片

一、開發環境説明

説明： 本案例同樣適用於 Windows 與 Linux，只需注意路徑配置及 pip.conf 寫法差異。

二、問題場景重現

在 PyCharm 的 Terminal 中執行以下命令時報錯：

pip install -r requirements.txt

輸出內容類似如下：

error: Subdirectory editable install not supported: 'path/to/module' missing 'pyproject.toml'

報錯含義解析

Markdown>引用語法
“Subdirectory editable install not supported”
表示 pip 無法以 -e（editable 模式）從子目錄安裝包，因為該路徑下缺少 pyproject.toml 文件或 setup 腳本。

三、問題分析思路

開發者 pip安裝器 本地子模塊 虛擬環境 執行 pip install -r requirements.txt 檢查 pyproject.toml / setup.py 缺失元數據文件 拋出錯誤 Subdirectory editable install not supported 檢查PYTHONPATH和導入路徑 修正後重新安裝成功 開發者 pip安裝器 本地子模塊 虛擬環境

四、常見原因與解決方案

1️⃣ module 包未安裝或包名錯誤

有時 requirements.txt 引用了不存在的路徑或拼寫錯誤的包名：

-e ./mymodul   # ❌錯誤拼寫

✅ 改為：

-e ./mymodule  # ✅正確路徑

2️⃣ 網絡問題，切換國內源鏡像

在國內網絡環境中，訪問 PyPI 經常超時。可配置 pip 源：

pip.conf (Linux/macOS)
路徑：~/.pip/pip.conf

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
timeout = 60

pip.ini (Windows)
路徑：%APPDATA%\pip\pip.ini

[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
timeout = 60

3️⃣ 沒有 __init__.py 文件

若自定義模塊未包含 __init__.py，Python 不會識別為包。
添加空文件即可解決。

4️⃣ 包版本不匹配

requirements.txt 示例：

numpy==1.26.0
pandas>=2.0

某些舊版包無法兼容新版 Python，建議執行：

pip install --upgrade pip setuptools wheel

5️⃣ 自定義包名衝突

假設你創建了一個名為 requests 的自定義模塊：

import requests  # 實際導入了你自己寫的requests.py

導致系統包被覆蓋。
✅ 改包名或調整路徑即可。

6️⃣ PYTHONPATH 未正確設置

在 macOS/Linux：

export PYTHONPATH=$PYTHONPATH:/Users/yourname/project

在 Windows：

set PYTHONPATH=%PYTHONPATH%;C:\project

PyCharm中：

File → Settings → Project → Python Interpreter → Environment Variables 手動添加。

7️⃣ 相對導入錯誤

不恰當地使用 from ..module import func 可能會引發導入路徑錯誤。
建議使用絕對導入或顯式修改 sys.path。

8️⃣ pip 版本過舊

pip install --upgrade pip

若仍出錯，可嘗試使用 setuptools 重新構建：

python setup.py install

五、深度進階方案

在子目錄中創建 pyproject.toml：

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

若使用 Poetry 或 Hatch，則分別調整 backend：

build-backend = "poetry.core.masonry.api"

新版 pip 已支持 pyproject.toml + 可編輯模式：

pip install -e .

確保 pyproject.toml 中添加以下內容：

[tool.setuptools]
packages = ["your_module"]

六、問題排查總結表

七、更多進階技巧

1. 使用 pip check 檢查依賴衝突
2. 使用 pipdeptree 可視化依賴關係
3. 使用 poetry lock 管理多模塊項目依賴
4. 使用 requirements.in + pip-tools 自動生成依賴樹

八、數學原理小插曲（LaTeX演示）

有時版本衝突的根本原因來自依賴約束的不兼容：

若結果大於零，則表示版本不一致。

九、結語與延伸閲讀

至此，我們完整分析了導致
pip install -r requirements.txt 出現 子目錄可編輯安裝缺少 pyproject.toml 的所有典型原因與多層解決方案。

温馨提示：
更多Bug解決方案請查看
==>全棧Bug解決方案專欄