Python 3.12 彻底物理移除 distutils，导致所有显式导入（如 from distutils.core import setup）均报 ModuleNotFoundError；根本原因是源码与C扩展已被删除，而非弃用或隐藏，必须升级 setuptools、改用 pyproject.toml 并弃用 setup.py。
Python 3.12 移除 distutils 不是 bug，是标准库瘦身的硬性落地 —— 所有依赖它动态加载、继承或调用的旧构建逻辑都会当场失效。
为什么 import distutils 直接报错？
Python 3.12 彻底删掉了 distutils 的源码和 C 扩展，不是“隐藏”或“弃用”，是物理移除。任何显式导入（如 from distutils.core import setup、from distutils.cmd import Command、import distutils.sysconfig）都会触发 ModuleNotFoundError。
常见触发点不在你写的代码里，而在这些地方：
- 旧版
setup.py文件开头还写着from distutils.core import setup - 依赖包如
capstone、APLpy、pyregion在初始化时偷偷 importdistutils.version或distutils.sysconfig - CI 脚本或 Dockerfile 里执行了
python setup.py install，而没换成pip install . - PyCharm 新建虚拟环境后没自动装
setuptools（尤其 Windows 上venv默认不带）
pip install 卡在 “Preparing metadata (setup.py)…” 怎么回事？
这是 pip 的兼容层在徒劳挣扎：它检测到项目没有 pyproject.toml，又不敢直接执行 setup.py（因为 distutils 已消失），于是尝试用 PEP 517 协议包装旧脚本，结果调用链断裂，要么报错，要么无限等待。
立即学习“Python免费学习笔记（深入）”；
典型表现：
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 终端卡住不动，CPU 占用低，几小时都没反应
- 日志里反复出现
Preparing metadata (setup.py)，但后续无输出 - 换用
pip install --no-build-isolation -v .可能提前暴露真实错误（比如No module named 'distutils.cmd'）
为什么 pip install distutils 没用？
PyPI 上那个叫 distutils 的包是空壳或文档包，不是官方移植，无法提供 distutils.cmd.Command 这类底层类，也不能修复 setup.py 中对 distutils 的继承逻辑。更危险的是，它可能掩盖真正问题，让 pip install . 表面成功，但生成的 wheel 缺少 requires_dist 等关键元数据。
真正该装的是：
-
pip install --upgrade setuptools wheel（setuptools ≥69.0才完整接管构建） -
python -m ensurepip --upgrade（确保 pip 自身构建能力不退化） - 必要时加
--force-reinstall，避免缓存残留旧行为
旧包（如 NumPy ≤1.25）安装失败的根本卡点
不是 pip 版本低，也不是网络问题，是构建过程本身断在了 Python 解释器层面：numpy==1.25.1 的 setup.py 会 import numpy.distutils，而这个子模块早在 NumPy 1.24 就被标记为废弃，Python 3.12 下直接找不到路径。
可行解只有两个方向：
- 升级到
numpy>=1.26.0（已完全移除numpy.distutils依赖） - 降级 Python 到 3.11（仅临时绕过，不解决生态适配）
- 绝对不要碰
pip install distutils或手动 patchsetup.py—— 后者极易引发 wheel 元数据缺失、依赖未声明等隐蔽故障
最常被忽略的一点：即使你把所有代码都改成了 from setuptools import setup，只要项目根目录下没有 pyproject.toml，pip 23+ 仍可能 fallback 到旧协议并试图加载 distutils —— 所以 pyproject.toml 不是可选项，是强制入口。
