不是 pip 本身坏了,而是现代 pip 默认用 PEP 517 隔离环境构建,若项目未通过 pyproject.toml 声明构建依赖(如 torch、numpy),或系统缺少编译工具,就会在“Building wheel”阶段报错。

直接结论:不是 pip 本身坏了,而是它现在默认用 PEP 517 隔离环境构建,而你的项目或依赖没告诉它“该装啥才能跑通 setup.py”。
为什么 pip install -e . 或 pip install xxx 会卡在 “Building wheel for xxx (PEP 517)”
现代 pip(≥21.3)对没有 pyproject.toml 的项目也会尝试走 PEP 517 流程:先建一个干净的临时环境,再安装构建依赖、再执行 setup.py。问题就出在这里——如果 setup.py 里写了 import torch 或 import numpy,但这个临时环境没装过它们,就会报 ModuleNotFoundError;如果项目依赖 toml 解析 pyproject.toml,但隔离环境里没装 toml,也会直接失败。
常见错误现象包括:
-
ModuleNotFoundError: No module named 'torch'(明明你 conda activate 后python -c "import torch"是通的) ImportError: No module named toml-
DeprecationWarning: The pymssql project has been discontinued(其实是构建时读setup.py报错,不是包本身不能用) ERROR: Could not build wheels for xxx which use PEP 517 and cannot be installed directly
必须加 pyproject.toml:声明构建期依赖
这是最规范、长期有效的解法。即使你只有 setup.py,也得补一个 pyproject.toml,明确告诉 pip:“构建这个包之前,先装这些包”。
在项目根目录新建 pyproject.toml,内容至少包含:
[build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta"
如果你的 setup.py 里 import 了第三方模块(比如 torch、numpy、cython),就把它们加进 requires:
从QuickView趋势笔记生成韩语AI播客包,含双人主持脚本(Callie×Nick)、Gemini多说话人TTS音频、字幕时间轴与渲染修正、缩略图+MP4包装及YouTube标题/描述输出。支持完整版(15~20分钟)和压缩版(5~7分钟)。
requires = ["setuptools>=64", "wheel", "torch>=2.0", "numpy"]-
requires = ["setuptools>=64", "wheel", "cython", "pybind11"](C++ 扩展常见)
注意:setuptools>=64 是关键门槛,低于这个版本不支持部分 PEP 517 行为;pip install --upgrade pip setuptools wheel 必做。
临时绕过隔离:用 --no-build-isolation
当你确认当前环境已经装好所有依赖(比如 torch + CUDA 工具链都在),只是不想让 pip 白建一遍隔离环境,可以用这个开关:
pip install -e . --no-build-isolationpip install pymssql --no-build-isolation
它等价于旧版的 python setup.py develop,跳过 PEP 517 构建流程,直接在当前 Python 环境里运行 setup.py。但要注意:
- 它不解决根本问题,只适合调试或 CI 临时 workaround
- 不能和
--use-pep517一起用(冲突) - 某些项目(如含复杂 CMakeLists.txt 的)可能仍会失败,因为编译器路径、CUDA_HOME 等环境变量未必被继承
系统级依赖缺失:Linux/macOS 常见硬伤
PEP 517 构建失败,有时根本不是 Python 层的问题,而是系统缺编译工具或头文件:
- Linux:
apt-get install -y build-essential python3-dev libssl-dev libffi-dev(Ubuntu/Debian)或yum groupinstall "Development Tools"(CentOS/RHEL) - macOS:
xcode-select --install(装 Command Line Tools),再确认which gcc和clang++ --version可用 - PyCUDA/pymssql 类包还依赖
nvcc或freetds-dev,需单独装
这类错误通常伴随大量 C 编译输出,最后一行是 error: command 'gcc' failed with exit status 1 或类似提示,此时看日志开头比死磕 PEP 517 更有效。
真正容易被忽略的点是:同一个项目,在不同机器上 pip install -e . 一个成功一个失败,大概率不是代码问题,而是构建依赖声明不全 + 系统工具链不一致。别急着降 pip 版本或删 --use-pep517——那个选项早在 pip 23.1 就被删了,强行加会报 no such option。

















