Python 3.12 彻底移除 distutils 模块，导致 import 失败；需升级 setuptools≥69.0、补 wheel、确保 pip≥24.1，并将 distutils 相关导入替换为 packaging.version 和 setuptools 对应组件。
ModuleNotFoundError: No module named 'distutils' 是硬删除，不是警告
Python 3.12 真的把 distutils 从源码里删干净了——没留 stub，不发警告，import 就炸。你看到这个错误，说明代码或依赖包里有 from distutils.core import setup、from distutils.version import LooseVersion 或 import distutils.cmd 这类调用，解释器启动时直接失败。
PyPI 上那个叫 distutils 的包是空壳，装了也没用；它不提供 distutils.cmd.Command 这类底层类，旧 setup.py 里继承它的自定义命令照样崩。
- CI 构建卡在
Preparing metadata (setup.py)：pip 检测到没pyproject.toml，又不敢执行已消失的distutils，于是死循环 - Docker 镜像用
FROM python:3.12-slim后pip install -r requirements.txt失败：环境里压根没预装setuptools - PyCharm 新建虚拟环境后右键 “Install package” 报错：IDE 内部仍走传统安装路径，没强制启用 PEP 517
pip install setuptools 不等于解决所有问题
pip install --upgrade setuptools 是必要动作，但不是万能解药。setuptools ≥69.0 才完整接管构建逻辑；低于这个版本，它仍会 fallback 到 distutils，结果还是报错。
真正要跑起来，还得补上 wheel 和确保 pip 自身不退化：
立即学习“Python免费学习笔记（深入）”；
- 运行
python -m ensurepip --upgrade，避免 pip 内部还依赖旧版构建链 - 确认
pip --version≥24.1（2024 年后发布的版本才稳定支持 PEP 517 fallback） - 如果项目没
pyproject.toml，pip 会尝试包装setup.py，但包装失败时只显示卡住或无限等待——加-v参数才能看到真实错误，比如No module named 'distutils.cmd'
旧项目迁移必须改三处关键代码
不能靠软链接或空包兜底，得动代码。核心替换点就三个，漏一个都可能静默失效：
-
from distutils.version import LooseVersion→ 改成from packaging.version import parse，然后用parse("1.2.3") > parse("1.2a1") -
from distutils.core import setup→ 改成from setuptools import setup，同时确保项目根目录存在pyproject.toml（哪怕只有最简 [build-system] 段） - 自定义构建命令（如
build_ext）别再继承distutils.command.build_ext，换成setuptools.command.build_ext
注意：MANIFEST.in 里的 include 规则行为在新版 setuptools 中也有差异，如果打包后缺文件，优先检查这个。
依赖包里藏着 distutils 更危险
你自己的代码可能没写 distutils，但依赖链里可能偷偷用了。比如：
-
APLpy<2.2.0在aplpy/core.py调distutils.version做版本比较 -
numpy<1.26的setup.py依赖numpy.distutils构建 C 扩展 -
torchvision<0.17的build_ext类继承自distutils.command.build_ext
这些在 Python 3.11 及之前能跑，是因为 distutils 还在；到了 3.12，要么当场报错，要么静默失效——比如 distutils.dir_util.copy_tree() 和 shutil.copytree(, symlinks=True) 行为不一致，部署时才发现文件没拷对。
最容易被忽略的是：错误可能不发生在安装阶段，而是在运行时首次 import 某个子模块才触发，调试成本远高于提前升级依赖。
