Python 3.12+ 报 ModuleNotFoundError: No module named 'distutils'

症状

换到 Python 3.12+（含 3.13/3.14）后，运行旧工具、激活新虚拟环境、或在 PyCharm 导入新解释器时直接报：

```

ModuleNotFoundError: No module named 'distutils'

```

特征：老项目/老工具链最常见——`from distutils.core import setup` 的旧 setup.py、依赖 distutils 的旧库、以及默认不带 setuptools 的新建 venv（3.12 起 venv 只带 pip 不再带 setuptools）。

原因

Python 3.12 起 **distutils 从标准库移除**（此前已废弃多年）：stdlib 里不再有 distutils 模块。同时 3.12 开始新建 venv 默认**只装 pip、不再预装 setuptools**，而 distutils 的替身（shim）恰好由 setuptools 提供——`import distutils` 实际映射到 `setuptools/_distutils`。所以报错本质是「环境中没有 setuptools，也就没有 distutils 替身」。

解法

按推荐顺序选：

1. **装 setuptools（最常见、秒级解决）**：`pip install setuptools`。装完 `import distutils` 即恢复（走 `setuptools/_distutils` 替身）。venv 环境就在 venv 里装；系统 Python 用 `sudo pip install setuptools` 或系统包管理装。

2. **顺手升级 pip/setuptools**：`python -m ensurepip --upgrade && pip install --upgrade setuptools pip`——老 pip（如 PyCharm 内置的 20.3.4）对 3.12+ 兼容差，常一起爆。

3. **系统包管理（Debian/Ubuntu，仅旧版 Python 有包）**：`sudo apt install python3-distutils`。注意该包通常只到 Python 3.11；3.12+ 的发行版不一定提供，优先用方案 1。

4. **长期正解（老项目迁移）**：旧 setup.py 改为 `pyproject.toml` + setuptools.build_meta（PEP 517），并删除代码里对 distutils 的直接 import。急着跑可以先装 setuptools 过渡，但 distutils 已 EOL，不会回来。

验证证据

- 本地实测（2026-08-29，WSL Ubuntu，Python 3.14.4 / pip 25.1.1）：

- 系统 Python：Ubuntu 预装 setuptools 78.1.1，`import distutils` 正常，实际加载路径是 `/usr/lib/python3/dist-packages/setuptools/_distutils/__init__.py`（替身生效）；

- 干净 venv（3.12+ 默认只带 pip 25.1.1、无 setuptools）：`import distutils` → 完整复现 `ModuleNotFoundError: No module named 'distutils'`，退出码 1；

- 修复：venv 内 `pip install setuptools` 后 `import distutils` 恢复，加载路径变为 venv 内 `setuptools/_distutils/__init__.py`，退出码 0；

- 结论与文章一致且修正其表述：setuptools 不是「依赖 distutils」，而是**提供 distutils 替身**；`python3-distutils` apt 包仅适用于旧版 Python，3.12+ 优先 `pip install setuptools`。

- 实测复现日志（2026-08-29）