RK3566 Ubuntu26.04 安装 Python3.12

在 RK3566 开发板（如立创·泰山派）运行 Ubuntu 系统时，由于后续部署视觉处理库（如 RGA Python ctypes 绑定、OpenCV）以及 RKNN 深度学习推理时，很多项目依赖固定版本的 Python 3.12 环境。

然而，在 Ubuntu 上升级或安装非系统默认版本的 Python 时，存在一个极高风险的陷阱：Ubuntu 底层的包管理工具（apt）、系统升级工具以及诸多系统守护进程严重依赖系统预装的 Python 版本。如果强行替换软链接或执行 make install，极易导致 apt 损坏、桌面环境崩溃等严重系统问题。

本文记录在 RK3566 aarch64 Ubuntu 系统下，通过源码编译并在独立目录安装 Python 3.12.8，通过 altinstall 实现与系统默认 Python 完美共存，并针对 2GB 内存开发板提供防 OOM 编译技巧。

一、安装编译依赖

编译 Python 需要一系列底层库（包括 OpenSSL、SQLite、FFI 等），若编译前未安装完备，后续会出现 pip 无法拉取 HTTPS 包、无法导入 _sqlite3 等疑难杂症：

sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  libffi-dev liblzma-dev

踩坑重点：
libssl-dev：必须安装，否则编译生成的 Python 会缺少 _ssl 模块，导致 pip 无法通过 HTTPS 下载任何包。
libsqlite3-dev：许多 Python 库（如日志、本地缓存）依赖 sqlite3。

二、下载 Python 3.12 源码包

以 Python 3.12.8 稳定版为例，在当前用户目录下下载并解压缩源码：

cd ~
wget https://www.python.org/ftp/python/3.12.8/Python-3.12.8.tgz
tar -xf Python-3.12.8.tgz
cd Python-3.12.8

三、配置编译选项（Configure）

为了避免污染系统目录并实现版本隔离，指定独立安装前缀 --prefix：

1	`./configure --prefix=/usr/local/python3.12 --enable-optimizations`

--prefix=/usr/local/python3.12：将所有可执行文件、库和头文件安装到指定独立目录，与系统环境完全隔离；
--enable-optimizations：启用 Profile-Guided Optimization (PGO) 优化编译，提升 Python 运行速度。

四、编译与安装（低内存防 OOM 重点）

RK3566 开发板（如泰山派）一般为 1GB 或 2GB 内存，多核全并发编译大型 C/C++ 工程时，内存容易耗尽触发 Linux 内核的 OOM Killer，导致编译器直接被系统杀死（终端提示 Killed）。

4.1 单线程编译

推荐使用 -j1 单线程编译：

1	`make -j1`

4.2 临时分配 Swap（可选应急方案）

若单线程编译中途依然出现 Killed，说明物理内存依然吃紧，可临时创建 2GB 的 Swap 交换分区：

# 临时创建并启用 2GB Swap 分区
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 查看内存与交换分区状态
free -h

编译完成后建议立即关闭 Swap，减少对开发板板载 eMMC 闪存的无谓擦写损耗：

1	`sudo swapoff /swapfile`

4.3 执行安装（⚠️ 核心操作：altinstall）

编译通过后，**必须使用 altinstall，千万不要使用 make install**：

1	`sudo make altinstall`

⚠️ 关键原理解析：
make install 会创建名为 python3 的软链接，直接覆盖 Ubuntu 系统的 /usr/local/bin/python3，导致系统内置脚本无法按预期版本运行，甚至直接弄瘫 apt。
make altinstall 则只会生成版本后缀明确的 python3.12 与 pip3.12，绝不会篡改任何系统的 python 或 python3 符号链接！

五、配置环境变量

将 Python 3.12 的 bin 路径添加到用户环境变量中：

1 2	`echo 'export PATH="/usr/local/python3.12/bin:$PATH"' >> ~/.bashrc source ~/.bashrc`

六、验证安装

检查 Python 3.12 及对应 pip 的版本输出：

1 2	`python3.12 -V pip3.12 -V`

正常输出示例：

1 2	`Python 3.12.8 pip 24.2 from /usr/local/python3.12/lib/python3.12/site-packages/pip (python 3.12)`

验证系统默认 Python 是否依然安全不受影响：

1	`python3 -V`

输出应依然为 Ubuntu 系统的默认 Python 版本，说明两者完全隔离共存。

七、配置 pip 国内镜像源

在嵌入式开发板上安装依赖时，建议配置国内镜像源以提升下载速度：

1 2	`pip3.12 config set global.index-url http://mirrors.aliyun.com/pypi/simple/ pip3.12 config set install.trusted-host mirrors.aliyun.com`

八、推荐：创建独立虚拟环境

后续在 RK3566 上开发 RGA 图像预处理、RKNN 推理或跑 Python 服务时，推荐通过 venv 创建独立虚拟环境，保持环境整洁且互不影响：

# 创建虚拟环境
python3.12 -m venv py312_env

# 激活虚拟环境
source py312_env/bin/activate

# 此时环境内的 python 和 pip 均自动指向 Python 3.12
python -V
pip -V

# 退出虚拟环境
deactivate

九、卸载与环境清理

如果后续不再需要该版本，由于采用了独立 --prefix 部署，卸载极为方便干净：

# 1. 直接删除安装目录
sudo rm -rf /usr/local/python3.12

# 2. 编辑 ~/.bashrc，删除添加的 PATH 那一行并重新生效
source ~/.bashrc

十、常见踩坑汇总

**绝对不要执行 make install**：
会覆盖系统默认 python3 软链接，导致系统级应用（如 apt 等）因版本不兼容报错崩溃。必须使用 sudo make altinstall。
**编译进程提示 Killed**：
开发板物理内存不足触发 OOM。使用 make -j1 并配合临时 Swap 分区解决。
pip 无法安装模块报 SSL 错误：
缺少 libssl-dev 导致 Python 编译时跳过了 _ssl 模块。需先补齐 libssl-dev 后重新 ./configure 并编译安装。
导入 sqlite3 报错：
缺少 libsqlite3-dev，在编译前安装该依赖库即可。