pip install .是唯一推荐方案,因Python 3.12已弃用setup.py安装,强制走PEP 517构建流程,自动读取pyproject.toml、调用build-backend、生成wheel后安装。

pip install . 是唯一推荐的平替方案
Python 3.12 中 python setup.py install 不仅被标记为 deprecated,而且在部分构建场景下会直接失败——它绕过 PEP 517 构建协议,忽略 pyproject.toml 中定义的 [build-system] 和动态元数据(如 dynamic = ["version"])。你看到的“安装成功但 import 失败”,大概率是因该命令没触发真正的构建阶段,只做了粗暴复制。
正确做法是统一改用:pip install .(当前目录)或 pip install -e .(开发模式)。这两条命令会:自动读取 pyproject.toml、调用指定的 build-backend(如 setuptools.build_meta)、生成 wheel、再安装。即使项目仍保留 setup.py,只要 pyproject.toml 存在且合法,setup.py 就会被静默忽略。
- 若报错
ModuleNotFoundError: No module named 'setuptools',先运行pip install --upgrade setuptools wheel—— Python 3.12 默认不带setuptools - CI/CD 脚本中所有
python setup.py bdist_wheel必须替换为pip wheel --no-deps --wheel-dir ./dist . - PyCharm 或 VS Code 启动虚拟环境后,记得手动
pip install setuptools,venv 默认不预装
遇到 AttributeError: module 'pkgutil' has no attribute 'ImpImporter' 怎么办
这不是你写的代码出问题,而是某个依赖(常见于旧版 setuptools、d2l、numpy.distutils 相关构建逻辑)在运行时试图访问已被物理删除的 pkgutil.ImpImporter。Python 3.12 彻底移除了 imp 模块及其所有绑定,没有兼容层,pip install imp 或 pip install distutils 都无效。
临时缓解可降级 setuptools 到 67.0.0(已知兼容),但更稳妥的是定位并修复源头:
立即学习“Python免费学习笔记(深入)”;
- 运行
pip install -v .查看完整 traceback,确认哪一行触发了ImpImporter - 若来自第三方库(如
d2l),检查其setup.py是否含from pkgutil import ImpImporter或imp相关导入,删掉并替换为importlib.util等效逻辑 - 若来自
numpy构建,必须升级到numpy >= 1.26并弃用numpy.distutils,改用setuptools+pybind11或meson-python
setup.py 还能留着吗?要不要全删掉
可以留,但不能依赖它驱动构建。Python 3.12 下,setup.py 的作用仅限于:被 setuptools.build_meta 当作配置源(当 pyproject.toml 中未覆盖对应字段时),或作为遗留文档参考。它不再参与实际构建流程。
真正起效的是 pyproject.toml。迁移建议:
- 新建最小化
pyproject.toml,至少包含:[build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta"
- 把原
setup.py中的name、version、install_requires等字段平移进pyproject.toml的[project]段 - 若用到
entry_points、extras_require或动态版本,必须用 TOML 格式重写;setup.py中的lambda或函数调用将被完全跳过
为什么 pip install . 有时还是报错,但 pip install -e . 却行
区别在于是否执行构建阶段:pip install . 会尝试构建 wheel 并安装;而 pip install -e .(editable mode)跳过构建,直接把当前路径加入 sys.path。所以后者成功,往往说明你的 pyproject.toml 或构建后端配置有误,导致 wheel 构建失败,但包结构本身是合法的。
排查重点:
- 检查
pyproject.toml中[build-system]的requires是否包含所需构建工具(如"meson-python"项目漏装meson-python) - 运行
python -m build --wheel --no-isolation单独测试构建流程,错误信息比pip install .更清晰 - 若项目使用
src/布局,确认[project]中设置了[[project.urls]]或packages = [{include = "mypackage", from = "src"}],否则pip install .可能找不到包
python setup.py 调用——它们不会在本地报错,却会让新成员首次拉取代码就卡住。


















