Python 环境修复手册：解决 ModuleNotFoundError: No module named 'distutils'

在基于 Debian/Ubuntu 的嵌入式系统（如 RK3528 运行 Armbian/Ubuntu Jammy）中，由于系统默认 Python 版本（3.10）与手动安装/更新的 Python 版本（3.13）共存，常会导致 pip 工具链因 distutils 模块缺失而崩溃。

问题分析 (Problem Analysis)

1.1 错误日志

当执行 pip3 install 时，系统抛出以下核心错误：

ModuleNotFoundError: No module named 'distutils'

1.2 根本原因

版本脱节：系统通过 apt 安装的 python3-distutils 软件包是专为 Python 3.10 提供的。
PEP 632 变更：从 Python 3.12 开始，distutils 模块正式从 Python 标准库中被移除。
环境混杂：您的系统当前正在运行 Python 3.13，但系统自带的 pip3 脚本仍然试图调用已不存在的 distutils 模块。

核心解决方案 (Solutions)

方案一：使用 get-pip.py 修复全局 Pip（最直接）

此方法会下载官方提供的引导脚本，它会根据当前活动的 Python 版本（3.13）安装一套自完备、不依赖系统旧模块的 pip。

# 1\. 下载脚本
curl -sS [https://bootstrap.pypa.io/get-pip.py](https://bootstrap.pypa.io/get-pip.py) -o get-pip.py

# 2\. 以 root 权限运行
sudo python3 get-pip.py

# 3\. 验证修复情况
pip3 --version

方案二：使用 venv 虚拟环境（生产环境推荐）

在开发板上，直接修改全局环境风险较高。虚拟环境会自动处理依赖关系并自带完整的构建工具。

# 1\. 安装配套的 venv 模块 (针对 3.13)
sudo apt update
sudo apt install python3.13-venv

# 2\. 在项目目录创建虚拟环境
python3 -m venv .venv

# 3\. 激活环境
source .venv/bin/activate

# 4\. 在虚拟环境下安装依赖
pip install -r requirements.txt

运维操作规范 (Operational Standards)

3.1 正确的 Pip 安装语法

在执行安装时，必须包含 install 关键字：

❌ 错误：pip3 -r requirements.txt
✅ 正确：pip3 install -r requirements.txt

3.2 明确指定 Python 解释器

如果系统存在多版本干扰，建议使用 python3 -m 模式，这能确保使用的 pip 与当前 Python 版本严格对应：

python3 -m pip install -r requirements.txt

常见问题排查 (Troubleshooting)

针对 RK3528 开发板的建议
保持系统更新：定期运行 sudo apt update && sudo apt upgrade。
避免删除系统 Python：系统底层组件（如 apt 自身）依赖原生的 Python 3.10，请勿尝试卸载旧版。
使用开发镜像源：若下载速度慢，可修改 /etc/apt/sources.list 使用清华大学或阿里云的镜像源。

文档版本：v1.0

适用硬件：Rockchip RK3528 (Arm64)

适用系统：Ubuntu 22.04 LTS (Jammy)

©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成，浏览时请结合常识与多方信息审慎甄别。
平台声明：文章内容（如有图片或视频亦包括在内）由作者上传并发布，文章内容仅代表作者本人观点，简书系信息发布平台，仅提供信息存储服务。

Python 环境修复手册：解决 ModuleNotFoundError: No module named 'distutils'