Python 3.12 移除 distutils 导致 setup.py install 失效，pip 23+ 默认忽略 setup.py 并强制使用 pyproject.toml 中声明的构建后端。
因为 distutils 已被 Python 3.12 正式弃用，而 setup.py 的传统安装路径严重依赖 distutils —— 没有它，setup.py install 就跑不起来。
distutils 被移除是根本原因
Python 3.10 开始对 distutils 发出弃用警告；3.12 中它已完全从标准库中删除（PEP 632）。而旧式 setup.py install 的底层逻辑直接调用 distutils.core.setup，哪怕你写了 from setuptools import setup，setuptools 在老版本里仍会 fallback 到 distutils 实现。一旦 distutils 消失，导入就失败：
ModuleNotFoundError: No module named 'distutils'
这不是 setuptools 版本低的问题，是 Python 解释器本身拒绝加载。
pip 不再执行 setup.py 脚本
PEP 517 强制要求：构建入口必须是声明式配置，不能是可执行代码。所以 pip 23+ 遇到含 pyproject.toml 的项目时，会忽略 setup.py，只按 [build-system] 指定的后端（如 setuptools.build_meta）来调用标准 API。即使你手动运行 python setup.py install，只要 setuptools ≥61.0，它也会报错：
立即学习“Python免费学习笔记（深入）”；
ERROR: Command "python setup.py install" failed with error code 1
- 新版 setuptools 主动禁用了
install命令（仅保留build、sdist等构建命令） -
setup.py文件本身变成“仅文档用途”，不再参与实际构建流程 - IDE、CI 工具也无法再靠执行
setup.py提取元数据（比如依赖列表、版本号）
为什么“Preparing metadata (setup.py)…”会卡住
这个提示其实是 pip 的兼容层在挣扎：它检测到项目没有 pyproject.toml，但又不敢直接运行 setup.py（因 distutils 缺失），于是尝试用 PEP 517 协议包装旧脚本，结果失败或无限等待。常见于：
- 老旧项目未迁移到
pyproject.toml - 本地开发时误删了
pyproject.toml，只剩setup.py - 某些 CI 镜像预装了极老版 pip（
此时 pip 不是“慢”，而是逻辑上走不通 —— 它既不能安全执行脚本，又没配置可用后端。
迁移只需三步，但必须做
不用重写整个构建逻辑，只需补一个最小可用的 pyproject.toml：
[build-system] requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta" [project] name = "your-package" version = "0.1.0" dependencies = ["requests"]
-
[build-system]是强制段，告诉 pip “用谁来构建”，缺了就触发 legacy 模式（已失效） -
[project]替代原来setup.py里的参数，所有字段名保持一致（如name、version、dependencies） - 保留
setup.py文件无害，但它不会再被读取 —— 删掉也行，别再往里加逻辑
真正的复杂点在于：很多项目曾把动态逻辑塞进 setup.py（比如读 __version__.py、根据平台开关依赖）。这些现在得改用 dynamic 字段 + setuptools 插件，或者提前生成静态值 —— 否则构建会失败，且错误信息往往藏在子进程日志里，不容易定位。
