一、背景说明
最近在飞凌 RK3568 核心板适配 OpenHarmony 5.1 系统时，需要在开发板上运行 Python 脚本，例如：
python3 xxx.py pip3 install pyomo但是 OpenHarmony 标准系统不是 Ubuntu，开发板上没有apt，也不能直接通过：
apt install python3来安装 Python。
因此最终采用的方案是：
Ubuntu 编译主机 ↓ 下载 python_oh 适配仓库 ↓ 交叉编译 CPython 3.13.5 ↓ 把 Python 组件加入 OpenHarmony 5.1 产品配置 ↓ 重新编译 ok3568 固件 ↓ 烧录到 RK3568 开发板 ↓ 开发板上直接运行 python3 / pip3本文记录完整成功过程和踩坑点。
二、开发环境
本文使用环境如下：
开发板：飞凌 RK3568 / OK3568-C 系统：OpenHarmony 5.1 内核：Linux 6.6 产品名：ok3568 编译主机：Ubuntu 20.04 Python 版本：CPython 3.13.5 源码目录： /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release平时内核编译命令是：
./build.sh -p ok3568 --ccache --build-target kernel --gn-args linux_kernel_version=\"linux-6.6\"但是注意：这个命令只编译内核，不会把 Python 打进系统镜像。
Python 属于用户态程序，需要编译cpython组件或者重新编译完整固件。
三、下载 python_oh 适配仓库
进入 OpenHarmony 源码根目录：
cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release下载适配仓库：
git clone -b 5.1.0_cpython_3.13.5 https://gitee.com/OpenHarmony_Python/python_oh.git python_oh如果遇到：
Could not resolve host: gitee.com说明 Ubuntu 虚拟机 DNS 或网络有问题，先检查：
ping -c 3 223.5.5.5 ping -c 3 gitee.com cat /etc/resolv.conf可以临时设置 DNS：
sudo tee /etc/resolv.conf > /dev/null <<'EOF' nameserver 223.5.5.5 nameserver 114.114.114.114 nameserver 8.8.8.8 EOF四、安装 Ubuntu 编译依赖
安装基础依赖：
sudo apt update sudo apt install -y \ autoconf \ automake \ libtool \ texinfo \ xutils-dev \ cmake \ tcl8.6 \ git \ patch如果sudo apt update里有 Docker 源报错，例如：
The repository 'https://download.docker.com/linux/ubuntu focal Release' no longer has a Release file只要后续依赖能正常安装，可以先不处理 Docker 源。
五、安装宿主机 Python 3.13
python_oh/build_python_oh.sh脚本会检查宿主机有没有python3.13：
grep -Rni "python3.13\|python3 " build_python_oh.sh BUILD.gn bundle.json 5.1.0_3568_add_python.patch可以看到类似：
build_python_oh.sh:54:if command -v python3.13 &>/dev/null; thenUbuntu 20.04 默认 apt 源可能没有python3.13，执行：
sudo apt install -y python3.13可能报：
E: Unable to locate package python3.13这时建议源码安装宿主机 Python 3.13.5。
安装依赖：
sudo apt install -y \ build-essential \ wget \ libssl-dev \ zlib1g-dev \ libbz2-dev \ libreadline-dev \ libsqlite3-dev \ libffi-dev \ liblzma-dev \ uuid-dev下载并编译：
cd /tmp wget https://www.python.org/ftp/python/3.13.5/Python-3.13.5.tgz tar -xf Python-3.13.5.tgz cd Python-3.13.5 ./configure --prefix=/opt/python3.13 --enable-shared make -j$(nproc) sudo make altinstall配置动态库路径：
echo "/opt/python3.13/lib" | sudo tee /etc/ld.so.conf.d/python3.13.conf sudo ldconfig建立软链接：
sudo ln -sf /opt/python3.13/bin/python3.13 /usr/local/bin/python3.13验证：
python3.13 --version正常输出：
Python 3.13.5注意：不要把系统默认/usr/bin/python3改掉，否则可能影响 Ubuntu 和 OpenHarmony 编译工具。
六、打 Python 集成补丁
进入源码根目录：
cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release先 dry-run：
patch --dry-run -p1 < python_oh/5.1.0_3568_add_python.patch如果没有明显报错，再正式打补丁：
patch -p1 < python_oh/5.1.0_3568_add_python.patch打完后检查是否加入了 python_oh 子系统：
grep -Rni "cpython\|python_oh\|python3.13" \ build/subsystem_config.json \ productdefine \ vendor \ device \ 2>/dev/null | head -100正常能看到类似：
build/subsystem_config.json:226: "python_oh": { build/subsystem_config.json:227: "path": "python_oh", build/subsystem_config.json:228: "name": "python_oh" vendor/hihope/rk3568/config.json:287: "subsystem": "python_oh", vendor/hihope/rk3568/config.json:290: "component": "cpython",七、关键踩坑：补丁默认加到了 rk3568，不是 ok3568
这里是最关键的地方。
原补丁是给rk3568产品写的，但是本项目实际编译命令是：
./build.sh -p ok3568 ...所以如果只打原补丁，后面执行：
./build.sh -p ok3568 --ccache --build-target cpython --target-cpu arm64会报：
ninja: error: unknown target 'cpython'原因是：
python_oh 子系统已经加入 build/subsystem_config.json 但是 cpython 组件只被加入 vendor/hihope/rk3568/config.json 实际编译的是 ok3568 所以 ok3568 产品配置里没有 cpython解决方法：把下面这段加入ok3568 对应的 config.json里。
先找到 ok3568 产品配置文件：
grep -Rni "\"ok3568\"" vendor productdefine device 2>/dev/null | head -100或者：
find vendor productdefine device \ -type f -name "config.json" \ -print | xargs grep -n "\"product_name\".*ok3568\|\"product_name\": \"ok3568\"" 2>/dev/null找到 ok3568 的config.json后，在"subsystems"数组中加入：
{ "subsystem": "python_oh", "components": [ { "component": "cpython", "features": [] } ] }注意 JSON 逗号格式。
修改后验证：
grep -Rni "\"subsystem\": \"python_oh\"\|\"component\": \"cpython\"" vendor productdefine device 2>/dev/null必须能在 ok3568 的配置文件中看到python_oh和cpython。
八、交叉编译 CPython
进入python_oh目录：
cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release/python_oh执行脚本：
chmod +x build_python_oh.sh bash build_python_oh.sh如果脚本提示找不到python3.13，说明第五步宿主机 Python 3.13 没装好。
编译完成后，可以回到源码根目录查生成物：
cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release find . -name "python3" 2>/dev/null | head -20 find . -name "libpython3.13*" 2>/dev/null | head -20 find . -path "*python3.13*" 2>/dev/null | head -20九、重新生成 Ninja 并编译 cpython 目标
如果之前已经生成过out/ok3568，需要清理旧的 Ninja 文件，否则它不知道新加的 cpython 组件：
cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release rm -rf out/ok3568/build.ninja rm -rf out/ok3568/args.gn rm -rf out/ok3568/obj/python_oh rm -rf out/ok3568/gen/python_oh然后编译 cpython：
./build.sh -p ok3568 --ccache --build-target cpython --target-cpu arm64 --gn-args linux_kernel_version=\"linux-6.6\"如果还报：
ninja: error: unknown target 'cpython'说明ok3568的产品配置没有真正包含python_oh/cpython，继续检查：
grep -Rni "cpython\|python_oh\|python3.13" \ build/subsystem_config.json \ productdefine \ vendor \ device \ 2>/dev/null | head -100也可以查看 Ninja 是否识别到 Python 目标：
./prebuilts/build-tools/linux-x86/bin/ninja \ -C out/ok3568 \ -t targets all | grep -i "cpython\|python_oh\|python3.13" | head -100十、编译完整系统镜像
cpython编译通过后，需要编完整系统镜像：
./build.sh -p ok3568 --ccache --gn-args linux_kernel_version=\"linux-6.6\"注意：这里不要加：
--build-target kernel因为只编 kernel 不会把 Python 打进系统分区。
两类命令的区别如下：
# 只编内核，适合驱动、DTS、触摸、网口等调试 ./build.sh -p ok3568 --ccache --build-target kernel --gn-args linux_kernel_version=\"linux-6.6\" # 单独编 Python 组件 ./build.sh -p ok3568 --ccache --build-target cpython --target-cpu arm64 # 编完整系统镜像，Python 要靠这个进固件 ./build.sh -p ok3568 --ccache --gn-args linux_kernel_version=\"linux-6.6\"编译完成后查镜像：
find out/ok3568 -name "system.img" -o -name "vendor.img" -o -name "updater.img"然后按飞凌 RK3568 原来的烧录流程烧录即可。
十一、开发板上验证 Python 是否安装成功
烧录启动后，进入开发板：
hdc shell查看 Python：
which python3 which python3.13 which pip3如果which找不到，可以手动搜索：
find /system -name "python3*" 2>/dev/null find /vendor -name "python3*" 2>/dev/null find / -name "python3*" 2>/dev/null测试版本：
python3 --version或者：
python3.13 --version正常应该看到类似：
Python 3.13.5测试标准库：
python3 -c "import sys, os, json, socket; print(sys.version); print('python ok')"如果输出：
python ok说明 Python 基本可用。
十二、测试 pip
查看 pip：
python3 -m pip --version安装纯 Python 库，例如 Pyomo：
python3 -m pip install pyomo -i https://mirrors.aliyun.com/pypi/simple如果报证书错误：
SystemTimeWarning: System time is way off SSLCertVerificationError: certificate verify failed: certificate is not yet valid说明开发板系统时间不对，先设置时间：
date date -s "2026-05-10 10:00:00" date然后重新安装：
python3 -m pip install pyomo -i https://mirrors.aliyun.com/pypi/simple如果还是 SSL 问题，可以临时加：
python3 -m pip install pyomo \ -i https://mirrors.aliyun.com/pypi/simple \ --trusted-host mirrors.aliyun.com验证：
python3 -c "import pyomo; print(pyomo.__version__)"十三、开发板 DNS 配置问题
如果 pip 或网络访问不正常，先区分是网络不通还是 DNS 不通。
测试公网 IP：
ping 223.5.5.5如果 IP 能通，但域名不通：
ping www.baidu.com报：
Name does not resolve说明是 DNS 问题。
OpenHarmony 根分区可能默认只读，需要先重新挂载：
mount -o remount,rw / mount -o remount,rw /system 2>/dev/null mount -o remount,rw /vendor 2>/dev/null写入 DNS：
printf "nameserver 223.5.5.5\nnameserver 114.114.114.114\nnameserver 8.8.8.8\n" > /etc/resolv.conf sync cat /etc/resolv.conf如果 DNS 仍然不生效，可以临时用 hosts 验证：
mount -o remount,rw / echo "110.242.68.4 www.baidu.com" >> /etc/hosts ping www.baidu.com如果写 hosts 后能 ping 通，说明网络路由没问题，问题集中在 DNS 解析链路。
十四、FastAPI 踩坑：pydantic_core 缺失
安装 FastAPI 后，如果运行：
python3 ./webmain.py报：
ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'原因是新版 FastAPI 默认依赖 Pydantic v2，而 Pydantic v2 依赖 Rust 写的pydantic-core本地二进制扩展。OpenHarmony 上通常没有现成可用的 wheel。
解决方法：降级到 FastAPI + Pydantic v1 组合。
python3 -m pip uninstall -y fastapi pydantic pydantic-core安装旧版组合：
python3 -m pip install \ "fastapi==0.99.1" \ "pydantic==1.10.24" \ "starlette==0.27.0" \ "uvicorn==0.22.0" \ -i https://mirrors.aliyun.com/pypi/simple \ --trusted-host mirrors.aliyun.com不要安装：
uvicorn[standard]因为它会拉取uvloop、httptools、watchfiles等二进制依赖，在 OpenHarmony 上容易失败。
测试：
python3 - <<'EOF' from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class Item(BaseModel): name: str value: int print("fastapi import ok") EOF十五、总结
最终成功方案如下：
1. Ubuntu 编译机准备依赖 2. 安装宿主机 Python 3.13.5 3. 下载 python_oh 仓库 4. 执行 5.1.0_3568_add_python.patch 5. 注意补丁默认加到 rk3568，需要手动把 python_oh/cpython 加入 ok3568 的 config.json 6. 执行 build_python_oh.sh 交叉编译 CPython 7. 编译 cpython 目标 8. 编译完整 ok3568 系统镜像 9. 烧录 RK3568 开发板 10. 在开发板上验证 python3 / pip3核心命令汇总：
cd /media/ycd/zhutou/OpenHarmony5_1/HononyOs/forlinx-5.1-release git clone -b 5.1.0_cpython_3.13.5 https://gitee.com/OpenHarmony_Python/python_oh.git python_oh patch --dry-run -p1 < python_oh/5.1.0_3568_add_python.patch patch -p1 < python_oh/5.1.0_3568_add_python.patch # 手动确认 ok3568 config.json 中加入 python_oh/cpython cd python_oh chmod +x build_python_oh.sh bash build_python_oh.sh cd .. rm -rf out/ok3568/build.ninja rm -rf out/ok3568/args.gn rm -rf out/ok3568/obj/python_oh rm -rf out/ok3568/gen/python_oh ./build.sh -p ok3568 --ccache --build-target cpython --target-cpu arm64 --gn-args linux_kernel_version=\"linux-6.6\" ./build.sh -p ok3568 --ccache --gn-args linux_kernel_version=\"linux-6.6\"开发板验证：
python3 --version python3 -c "import sys, os, json, socket; print(sys.version); print('python ok')" python3 -m pip --version python3 -m pip install pyomo -i https://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com最终效果：
OpenHarmony 5.1 / RK3568 开发板成功运行 CPython 3.13.5 pip 可用 纯 Python 包可安装 可以运行 Pyomo、简单 FastAPI 服务等 Python 程序需要注意的是，带 C/C++/Rust 本地扩展的 Python 包不一定能直接用，例如新版 Pydantic、numpy、opencv 等，需要单独交叉编译或选择纯 Python / 老版本替代方案。
