当前位置：首页 > news >正文

Ubuntu 20.04 下 OpenCV 4.5.4 编译安装与系统默认 OpenCV 4.2 共存切换指南【2025最新版！！！】

news 来源：原创 2025/6/17 15:03:44

引言

在图像处理与计算机视觉开发中，OpenCV 是不可或缺的基础库。然而，Ubuntu 20.04 默认的 APT 仓库只提供 OpenCV 4.2.0 版本，对于需要使用 OpenCV ≥ 4.5 的开发者（如 opencv-wechat-qrcode, dnn_superres, G-API 模块等）来说，系统源版本显然无法满足需求。
我在实际项目开发中也遇到了这个问题：系统自带 OpenCV 4.2 无法满足我的需求，而升级系统或使用非官方源又存在风险。因此，我选择通过源码自行编译 OpenCV 4.5.4，并实现与系统版本共存且可灵活切换。
这篇博客将完整记录我的配置流程，帮助你在 Ubuntu 20.04 下：

✅ 成功编译安装 OpenCV 4.5.4 到 /opt 等独立路径

✅ 保留系统 APT 安装的 OpenCV 4.2（不破坏原系统）

✅ 实现 C++/Python 下的版本灵活切换

一、系统默认 OpenCV 版本问题

Ubuntu 20.04 默认通过以下命令安装 OpenCV：

sudo apt install libopencv-dev python3-opencv

对应版本：

C++: OpenCV 4.2.0
Python: cv2 绑定也是 4.2.0

这对于需要使用 4.5 及以上新功能的用户来说，限制非常大。例如：

cv2.dnn_superres 模块在 4.3 后才加入
opencv-wechat-qrcode 仅在 4.5 后可用
更高版本 dnn 支持 ONNX/YOLOX 更完整

二、OpenCV 4.5.4 编译安装步骤

1、安装依赖项

sudo apt update
sudo apt install -y build-essential cmake git pkg-config \libgtk-3-dev libavcodec-dev libavformat-dev libswscale-dev \libtbb2 libtbb-dev libjpeg-dev libpng-dev libtiff-dev \libopenexr-dev libeigen3-dev libdc1394-22-dev libqt5opengl5-dev qtbase5-dev

2、下载源码（含 contrib）

mkdir -p ~/SoftWare && cd ~/SoftWare# OpenCV 主仓库
wget -O opencv-4.5.4.zip https://github.com/opencv/opencv/archive/4.5.4.zip
unzip opencv-4.5.4.zip# contrib 模块
wget -O opencv_contrib-4.5.4.zip https://github.com/opencv/opencv_contrib/archive/4.5.4.zip
unzip opencv_contrib-4.5.4.zip

3、编译配置

cd ~/SoftWare/opencv-4.5.4
mkdir build && cd build
cmake .. 
-DCMAKE_BUILD_TYPE=Release 
-DCMAKE_INSTALL_PREFIX=/opt/opencv-4.5.4 
-DOPENCV_EXTRA_MODULES_PATH=~/SoftWare/opencv_contrib-4.5.4/modules 
-DBUILD_EXAMPLES=OFF -DBUILD_TESTS=OFF -DBUILD_PERF_TESTS=OFF 
-DWITH_QT=ON -DWITH_OPENGL=ON -DWITH_TBB=ON 
-DOPENCV_GENERATE_PKGCONFIG=ON

参数	含义与用途
`cmake ..`	使用上一级目录（源码根）为输入，生成构建配置。一般在 `opencv-4.5.4/build` 中执行
`-DCMAKE_BUILD_TYPE=Release`	设置构建类型为 Release（开启编译器优化，如 `-O3`），通常用于生产部署而非调试
`-DCMAKE_INSTALL_PREFIX=/opt/opencv-4.5.4`	指定安装路径（而非默认的 `/usr/local`），这样就能与系统 apt 安装的 OpenCV 并存
`-DOPENCV_EXTRA_MODULES_PATH=~/SoftWare/opencv_contrib-4.5.4/modules`	添加 OpenCV Contrib 模块支持，如 `xfeatures2d`, `aruco`, `sfm`, `viz` 等
`-DBUILD_EXAMPLES=OFF`	不编译 `opencv/samples` 中的演示示例，节省时间和磁盘空间
`-DBUILD_TESTS=OFF`	不编译 OpenCV 内建测试（gtest），一般只有开发者才需要
`-DBUILD_PERF_TESTS=OFF`	不编译性能测试模块，除非你要 benchmark OpenCV
`-DWITH_QT=ON`	启用 Qt 支持（用于高质量 GUI 显示，替代原生 HighGUI）注意：依赖 `libqt5`
`-DWITH_OPENGL=ON`	启用 OpenGL 加速显示（搭配 GUI 更顺滑，支持 `cv::viz`, `imshow` 等）
`-DWITH_TBB=ON`	启用 Intel TBB 多线程加速（如图像并行处理、滤波等）要求系统安装 `libtbb-dev`
`-DOPENCV_GENERATE_PKGCONFIG=ON`	启用 pkg-config 安装支持，可通过`pkg-config --modversion opencv4`查询到OpenCV的版本

4、编码安装

make -j$(nproc)
sudo make install

此时，OpenCV 4.5.4 会被完整安装到 /opt/opencv-4.5.4，不会干扰系统原生 OpenCV 4.2。

三、多版本共存与切换方法

1、配置环境变量（建议写入 ~/.bashrc）

gedit ~/.bashrc#让 CMake 中的 find_package(OpenCV) 找到 4.5.4 的配置。
export OpenCV_DIR=/opt/opencv-4.5.4 #让 CMake 优先在 /opt 查找 OpenCV 的 include 和 lib。
export CMAKE_PREFIX_PATH=/opt/opencv-4.5.4:$CMAKE_PREFIX_PATH #让 pkg-config 正确输出 4.5.4 的版本和编译参数。
export PKG_CONFIG_PATH=/opt/opencv-4.5.4/lib/pkgconfig:$PKG_CONFIG_PATH#运行 C++ 可执行程序时能正确加载 4.5.4 的 .so 动态库。
export LD_LIBRARY_PATH=/opt/opencv-4.5.4/lib:$LD_LIBRARY_PATH#让 Python 3.8 能找到你自己编译的 cv2.so。
（可选）export PYTHONPATH=/opt/opencv-4.5.4/lib/python3.8/dist-packages/cv2/python-3.8:$PYTHONPATH

然后：

source ~/.bashrc

2、检察当前使用的版本

# C++ 编译器版本确认
pkg-config --modversion opencv4   # 输出：4.5.4
🔍 作用：
查询当前系统中 C++ 编译时使用的 OpenCV 版本（通过 pkg-config 机制）。📚 原理：
pkg-config 是 C/C++ 编译工具链中的一个工具，它根据 .pc 文件提供库的头文件路径、库路径、依赖等信息。它找的文件是：opencv4.pc，路径一般在：
/usr/lib/pkgconfig/opencv4.pc           # apt 安装版本
/opt/opencv-4.5.4/lib/pkgconfig/opencv4.pc   # 手动安装版本
需要设置好环境变量 PKG_CONFIG_PATH 才能切换版本。
✅ 用法示例：
pkg-config --modversion opencv4          # 查询版本
pkg-config --cflags opencv4              # 查询头文件路径
pkg-config --libs opencv4                # 查询链接库
💡 应用场景：
编写或编译 C++ 项目（例如 CMake/Makefile）时判断当前使用的 OpenCV 版本。
在多版本共存时，用来检测 pkg-config 实际解析的是哪个版本。# Python
python3 -c "import cv2; print(cv2.__version__)"  # 应输出 4.5.4
🔍 作用：
查看当前 Python 解释器中实际导入的 OpenCV（cv2 模块）的版本。📚 原理：
Python 使用的是 cv2 模块（通常为 cv2.cpython-3X-xxx.so 文件）。
模块所在路径由 sys.path 决定，而 PYTHONPATH 变量可以控制它的优先级。
如果你系统中装了多个 cv2，Python 会根据路径顺序选择导入。✅ 用法示例：
python3 -c "import cv2; print(cv2.__version__)"    # 打印版本
python3 -c "import cv2; print(cv2.__file__)"       # 查看使用的是哪个路径下的 cv2
💡 应用场景：
验证当前 Python 环境中的 OpenCV 是否为自定义版本（例如你手动编译的 4.5.4）。
检查虚拟环境或系统环境中的 cv2 模块来源。
解决 Python cv2 导入失败或版本不一致的问题。

特性	`pkg-config --modversion opencv4`	`python3 -c "import cv2"`
面向语言	C++	Python
获取来源	`.pc` 文件（OpenCV C++ 安装配置）	`cv2.so` 模块（Python 模块路径）
与谁相关	CMake/Makefile/ROS 等	Python 脚本/深度学习训练/推理
依赖环境变量	`PKG_CONFIG_PATH`	`PYTHONPATH`, `sys.path`
切换版本方式	通过 `.pc` 和环境变量切换	通过 `PYTHONPATH` 或 `pip` 安装控制
检查用途	编译链接库版本检测	Python 模块是否是你想用的版本

检察结果如下：

在这里插入图片描述

3、切换回系统默认版本

如果你想切回系统 OpenCV 4.2，只需：

将上述添加的环境变量注释掉即可

在这里插入图片描述
然后可以查询到：

四、多版本共存实用技巧

使用场景	推荐方式
使用 apt 默认版本（OpenCV 4.2）	不设置任何环境变量
使用自编译版本（OpenCV 4.5.4）	设置 `PKG_CONFIG_PATH`, `LD_LIBRARY_PATH`, `PYTHONPATH` 等
编译其他项目（如 SIBR, ROS）	在 `CMakeLists.txt` 中设置 `CMAKE_PREFIX_PATH=/opt/opencv-4.5.4`
Python 快速测试 `cv2` 版本	安装 pip 包或设置 `PYTHONPATH`