Python 3.12 中 distutils 被官方正式移除，导致 ModuleNotFoundError；根本解决法是安装 setuptools（≥64.0），它通过 _distutils 兼容层并配合 python -m pip 触发自动注入，实现无缝替代。
python学习
Python 编程学习助手 skill，面向零基础用户。 当用户表达以下意图时触发： - 学习 Python 基础概念（变量、数据类型、循环、函数、类等） - 请求 Python 练习题或测验 - 请求审查或调试 Python 代码 - 请求 Python 项目实战指导（爬虫、数据分析、Web 开发等入门项目） - 泛化表述如"教我 Python""我想学编程""Python 怎么写""帮我学 Python" 此 skill
下载
distutils 在 Python 3.12 中不是“报错”，而是被官方正式移除。你看到的
ModuleNotFoundError: No module named 'distutils' 不是安装失败，是环境干净得过了头——Python 3.12 的虚拟环境默认不带它，而很多老工具（比如
capstone、
pwntools、
node-gyp）还在代码里硬写了
import distutils.sysconfig。
真正该切换的不是“工具”，是兼容层：让依赖
distutils 的代码，自动落到
setuptools 提供的兼容实现上。
为什么 pip install setuptools 能“修好” distutils？
setuptools 从 60.x 版本起，把原
distutils 的核心逻辑重实现为
setuptools._distutils，并做了运行时注入。但这个注入默认不生效，除非满足以下任一条件：
- 已安装较新版本的
setuptools（≥64.0），且环境变量 SETUPTOOLS_USE_DISTUTILS=local 已设置
- 使用
python -m pip 安装（而非全局 pip 命令），因为 -m 模式会触发 setuptools 的自动适配钩子
- 在虚拟环境中首次调用
pip install 时，pip 自动升级自身并拉入兼容层（但前提是底层 pip 是通过 ensurepip 或 get-pip.py 安装的）
手动创建 distutils 软链接的风险与适用场景
Linux/macOS 下执行
ln -s setuptools/_distutils distutils 确实能让
import distutils 成功，但它绕过了
setuptools 的版本校验和路径管理：
- 如果后续升级
setuptools，_distutils 目录可能被重构或移动，软链接立刻失效
- 多个 Python 版本共存时，容易链错 site-packages，导致
ImportError: cannot import name 'sysconfig'
- 仅推荐用于嵌入式设备或 CI 构建镜像等无法改环境变量、又必须跑旧脚本的封闭场景
PyCharm / VS Code 中 pip 升级失败的典型卡点
在 IDE 内置终端中执行
python -m pip install --upgrade pip 报
distutils 错，往往是因为：
- IDE 绑定的是系统 Python（如
/usr/bin/python3），但该二进制实际指向的是 apt 安装的 Python 3.10，而你当前 shell 用的是手动编译的 3.12 —— 解释器和 pip 不匹配
- PyCharm 创建虚拟环境时未勾选 “Inherit global site-packages”，导致
pip 启动时找不到 setuptools 入口
- Windows 上 PowerShell 默认禁用脚本执行策略，
get-pip.py 下载后双击运行会静默失败，必须用 python get-pip.py
最稳的开局动作永远是：先确认解释器路径，再用
python -m ensurepip --upgrade 拉起一套与当前 Python 版本严格对齐的
pip +
setuptools 组合。之后所有
pip install 都加
-m，不图快，图确定性。
