Python 3.12 中 distutils 被官方正式移除，导致 ModuleNotFoundError；根本解决法是安装 setuptools（≥64.0），它通过 _distutils 兼容层并配合 python -m pip 触发自动注入，实现无缝替代。
Python 3.14.3
微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。
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，不图快，图确定性。
