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

你会遇到什么

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

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

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

Python 3.12 起 distutils 从标准库移除（此前已废弃多年）。

同时 3.12 开始新建 venv 默认只装 pip、不再预装 setuptools，而 distutils 的替身（shim）恰好由 setuptools 提供——import distutils 实际映射到 setuptools/_distutils。

报错本质是「环境中没有 setuptools，也就没有 distutils 替身」。

distutils 从 3.12 起从标准库移除，但真正的机制在「替身」：import distutils 实际上由 setuptools 的 _distutils 提供（setuptools 装一个 distutils shim 顶替）。

3.12 起新建 venv 默认只装 pip、不预装 setuptools——所以「import distutils 失败」的本质是「环境里没有 setuptools，也就没有替身」。

系统 Python 不报是因为发行版预装了 setuptools。

确定性推论：报 ModuleNotFoundError: No module named distutils 先查环境里有没有 setuptools（pip show setuptools）；两条正路——装 setuptools（pip install setuptools，替身回归）或改用 packaging/标准库替代（sysconfig、tomllib）；

旧项目别在 requirements 里固定删掉 setuptools（它同时是构建依赖）；

判断路径固定：同样的 import 在系统 Python 正常、在干净 venv 报错 = setuptools 缺失，不是代码问题。

一步步来

1. 装 setuptools — 必做

pip install setuptools

装完 import distutils 即恢复（走 setuptools/_distutils 替身）。

2. 顺手升级 pip/setuptools — 必做

python -m ensurepip --upgrade && pip install --upgrade setuptools pip

老 pip（如 PyCharm 内置的 20.3.4）对 3.12+ 兼容差，常一起爆。

3. 系统包管理（仅旧版 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，不会回来。

怎么确认修好了

import 恢复（实测输出形态）：

venv 内 pip install setuptools 后 → import distutils 恢复，exit 0（实测）
加载路径变为 venv 内 setuptools/_distutils/__init__.py（实测）

其它环境的表现

症状

换到 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，不会回来。