本文档说明

在泰山派3M-RK3576开发板上搭建 Python + OpenCV 开发环境，完成后将拥有一个可以运行 OpenCV 程序的虚拟环境。

为什么使用虚拟环境

Ubuntu 24.04 采用了 PEP 668 规范，禁止直接使用 pip 安装系统级 Python 包。直接执行 pip install 会报错：

error: externally-managed-environment

因此需要创建 Python 虚拟环境（venv） 来隔离安装 OpenCV 及其依赖，不会影响系统自带的 Python 包。

创建虚拟环境

注意

泰山派3M-RK3576 的 Ubuntu24 系统 apt 源中没有 python3.12-venv 包，需要用以下方式创建虚拟环境。

# 1. 创建虚拟环境（不含pip）
python3 -m venv --without-pip ~/opencv-env

# 2. 手动安装pip
curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
~/opencv-env/bin/python3 /tmp/get-pip.py

# 3. 激活虚拟环境
source ~/opencv-env/bin/activate

激活成功后，命令行前方会出现 (opencv-env) 标识：

(opencv-env) root@localhost:~#

如果开发板没有网络

参考下方 离线安装 章节，通过 ADB 推送安装包。

安装 OpenCV

在虚拟环境中使用 pip 安装：

pip install opencv-python numpy -i https://mirrors.aliyun.com/pypi/simple

包名	说明
opencv-python	完整版 OpenCV，包含 GUI 显示功能（cv2.imshow）
numpy	OpenCV 的核心依赖，用于图像数据的矩阵运算
-i ...aliyun...	使用阿里云镜像加速下载

安装过程需要下载约 50MB 文件（aarch64 架构预编译 wheel 包，无需本地编译），请耐心等待。

验证安装

python3 -c "import cv2; print('OpenCV version:', cv2.__version__)"
python3 -c "import numpy; print('NumPy version:', numpy.__version__)"

预期输出：

OpenCV version: 4.13.0
NumPy version: 2.4.6

关于 Qt 字体警告

运行带窗口显示的脚本时可能看到如下警告，不影响功能，忽略即可：

QFontDatabase: Cannot find font directory .../cv2/qt/fonts.
Note that Qt no longer ships fonts.

每次使用前的准备

每次打开新终端，都需要先激活虚拟环境：

source ~/opencv-env/bin/activate

退出虚拟环境：

deactivate

设置快捷别名（推荐）

echo 'alias cv="source ~/opencv-env/bin/activate"' >> ~/.bashrc
source ~/.bashrc

之后只需输入 cv 即可快速激活环境。

一键启动脚本

cat > ~/start_opencv.sh << 'SCRIPT'
#!/bin/bash
source ~/opencv-env/bin/activate
echo "OpenCV环境已激活 (版本: $(python3 -c 'import cv2;print(cv2.__version__)'))"
echo "摄像头: $(v4l2-ctl --list-devices 2>/dev/null | grep -A1 usb | grep /dev/video | head -1)"
SCRIPT
chmod +x ~/start_opencv.sh

运行 source ~/start_opencv.sh 即可一键启动开发环境。

离线安装

如果开发板没有网络，可以在 PC 上下载后通过 ADB 推送：

在 PC 上操作：

# 下载 get-pip.py
curl -sS https://bootstrap.pypa.io/get-pip.py -o get-pip.py

# 下载 wheel 包（注意指定 aarch64 平台）
pip download opencv-python numpy \
    --platform manylinux_2_28_aarch64 \
    --only-binary=:all: -d ./wheels

# 推送到开发板
adb push get-pip.py /tmp/get-pip.py
adb push ./wheels /tmp/wheels

在开发板上操作：

# 创建虚拟环境
python3 -m venv --without-pip ~/opencv-env

# 安装 pip
~/opencv-env/bin/python3 /tmp/get-pip.py

# 激活环境并安装 OpenCV
source ~/opencv-env/bin/activate
pip install /tmp/wheels/*.whl

常见问题

python3 -m venv 报错 "returned non-zero exit status 1"

ensurepip 模块缺失，使用 --without-pip 参数绕过：

python3 -m venv --without-pip ~/opencv-env

然后手动安装 pip（见上方步骤）。

import cv2 报错 "libGL.so.1: cannot open shared object file"

安装 OpenGL 相关库：

sudo apt install -y libgl1

TIP

如果 apt 无法联网，可以使用 opencv-python-headless 替代 opencv-python，但将无法使用 cv2.imshow() 显示窗口。

安装时提示 "No space left on device"

开发板存储空间不足，使用 df -h 查看磁盘使用情况，清理不需要的文件后重试。