OpenCV 4.x Ubuntu 实战指南：从系统包到源码编译的 Python 绑定安装全解析

本篇指南基于 OpenCV 官方教程 Ubuntu 安装页，系统讲解在 Ubuntu 系统上安装 OpenCV-Python 的两种途径——apt 预编译包安装与源码编译构建，并深入到 CMake 构建系统的 Python 探测逻辑、最低版本约束与关键构建选项，帮助读者既能快速装好 cv2，又能理解 cmake ../ 背后发生了什么。

前置说明：为什么官方优先推荐 PyPI 二进制

教程开篇即给出一个重要提示：如果可能，请优先使用 PyPI 分发的二进制包。详见 pip 安装教程，其核心操作仅三步：

python -m venv .venv
source .venv/bin/activate
pip install opencv-python        # 或 opencv-contrib-python / opencv-python-headless

Ubuntu 安装教程的价值在于两条进阶路线：使用 Ubuntu 发行版自带的预编译包（快速但版本可能滞后），以及从源码完整编译（获得最新版本、自定义模块组合，也是日后参与 OpenCV 贡献的必备技能）。此外 OpenCV-Python 的硬依赖只有一项——NumPy；教程还建议安装 Matplotlib（可视化）与 IPython（交互式终端），二者均为可选但推荐。

路线一：从 apt 仓库安装预编译包

这条路最适合“只写代码、不关心构建”的开发者，整个过程只需一条命令（需要 root 权限）：

sudo apt-get install python3-opencv

安装完成后，打开 Python（IDLE 或 IPython）终端验证：

import cv2 as cv
print(cv.__version__)

若版本号正常打印且无报错，说明安装成功。

这条路线的固有短板

教程明确指出了 apt 方案的局限：

• 版本滞后：Ubuntu 软件源中的 OpenCV 版本未必是最新的（教程写作时软件源为 2.4.8，而主线已是 3.x）。对 Python API 而言，新版本意味着更好的支持面与最新的 bug 修复；
• 无法满足贡献需求：如果你希望向 OpenCV 提交代码，必须走源码编译路线。

这也是教程把“从源码构建”作为主体篇幅展开的原因。

路线二：从源码构建 OpenCV

源码编译初见复杂，实际流程固定为：安装依赖 → 获取源码 → 创建 build 目录 → CMake 配置 → 编译安装。

2.1 必需构建依赖

必需依赖分四类：构建工具链（CMake、GCC）、Python 开发环境（python3-dev、NumPy 头文件）、GUI/相机/媒体支持（GTK、V4L、FFmpeg/GStreamer）。完整命令如下：

# 构建工具链
sudo apt-get install cmake
sudo apt-get install gcc g++

# Python 3 支持
sudo apt-get install python3-dev python3-numpy

# 媒体支持（FFmpeg / GStreamer）
sudo apt-get install libavcodec-dev libavformat-dev libswscale-dev
sudo apt-get install libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev

# GUI 支持（二选一或都装）
sudo apt-get install libgtk2.0-dev   # GTK2
sudo apt-get install libgtk-3-dev    # GTK3

说明：教程原文在 GCC 之后提到 Python-devel 与 NumPy 是构建 Python 绑定的必需项；上表中的 python3-numpy 正是为了让构建系统能探测到 NumPy 头文件（探测原理见后文 2.4 节）。

2.2 可选依赖：用系统库替换内置编解码库

OpenCV 源码中自带（bundle）了 PNG、JPEG、TIFF、WebP 等图像格式的第三方实现（对应仓库中的 3rdparty/libpng、3rdparty/libjpeg-turbo、3rdparty/libtiff、3rdparty/libwebp 等目录），但内置版本可能较旧。若希望改用系统最新版本的编解码库，可安装对应的开发包：

sudo apt-get install libpng-dev
sudo apt-get install libjpeg-dev
sudo apt-get install libopenexr-dev
sudo apt-get install libtiff-dev
sudo apt-get install libwebp-dev

注意：在旧版 Ubuntu（如 16.04）上还可额外安装 libjasper-dev 获得系统级 JPEG2000 支持。这些全部是可选项——不装时 OpenCV 会自动回退到内置库，构建不会失败。

2.3 获取源码并创建独立的 build 目录

若未来计划参与 OpenCV 贡献，用 Git 克隆源码仓库（先 sudo apt-get install git）；否则可直接下载发布版源码包。获取后进入源码目录并创建 build 目录：

sudo apt-get install git
git clone https://github.com/opencv/opencv.git

cd opencv
mkdir build
cd build

“在源码树之外单独建 build 目录”不是习惯问题，而是构建系统的硬性约束。仓库根目录 CMakeLists.txt 中有显式检查：

# Disable in-source builds to prevent source tree corruption.
if(" ${CMAKE_SOURCE_DIR}" STREQUAL " ${CMAKE_BINARY_DIR}")
  message(FATAL_ERROR "
FATAL: In-source builds are not allowed.
       You should create a separate directory for build files.
")
endif()

即如果在源码目录内直接运行 cmake .，构建会立即中止并报 FATAL: In-source builds are not allowed。

2.4 配置：cmake ../ 与 Python 探测

在 build 目录下执行：

cmake ../

CMake 负责决定：安装哪些模块、安装路径、使用哪些附加库、是否编译文档与示例等，绝大多数工作由默认参数自动完成。有两个与教程描述一一对应的默认行为，可以在源码中确认：

• 默认构建类型为 Release。CMakeLists.txt 中：当未指定 CMAKE_BUILD_TYPE 时，会打印 "'Release' build type is used by default" 并强制设为 Release，这与教程“OpenCV defaults assume Release build type”的表述完全一致；
• 默认安装路径为 /usr/local，故教程提示 make install 需要 root 权限（sudo make install）。

配置成功的关键标志是 CMake 输出中的 Python 3 探测块，形如：

--   Python 3:
--     Interpreter:                 /usr/bin/python3.4 (ver 3.4.3)
--     Libraries:                   /usr/lib/x86_64-linux-gnu/libpython3.4m.so (ver 3.4.3)
--     numpy:                       /usr/lib/python3/dist-packages/numpy/core/include (ver 1.8.2)
--     packages path:               lib/python3.4/dist-packages

这四行不是装饰，它对应仓库 cmake/OpenCVDetectPython.cmake 中 find_python() 的完整探测链：

1. 定位 Python3 解释器、版本字符串与解释器所在路径；
2. 通过 PYTHON3_LIBRARY 找到 libpython3.x.so（即输出中的 Libraries 行）；
3. 通过执行 python -c "import numpy; print(numpy.get_include())" 探测 NumPy 头文件目录，并通过 python -c "import numpy; print(numpy.version.version)" 获取版本（见 OpenCVDetectPython.cmake）。这正是 2.1 节中必须安装 python3-numpy 的原因——探测失败则 cv2 绑定不会构建；
4. 计算 packages path（输出中的 lib/python3.4/dist-packages），即构建出的 Python 包将被安装到的站点包相对路径。

两个相关 CMake 变量可供高级用户控制：

• OPENCV_PYTHON3_VERSION：可选缓存选项（OpenCVDetectPython.cmake），用于在多 Python 版本共存时指定要绑定的解释器版本；
• PYTHON3_NUMPY_INCLUDE_DIRS 等变量：在交叉编译等无法自动探测的场景下手动指定。

2.5 版本约束速查

教程标注“已在 Ubuntu 16.04 / 18.04（64 位）上验证”，但对构建工具链的硬性下限由仓库源码直接定义。cmake/OpenCVMinDepVersions.cmake 中：

set(MIN_VER_CMAKE 3.13)  # Debian 10
set(MIN_VER_PYTHON3 3.2)

即：CMake ≥ 3.13、Python ≥ 3.2。若你的 Ubuntu 版本较新（CMake 随发行版升级），这两条默认满足；反之需要升级 CMake 或 Python 才能通过配置。

编译与安装

配置无误后执行：

make            # 可加 -j$(nproc) 并行加速（多核机器上显著缩短时间）
sudo make install

所有产物安装到 /usr/local/ 下。最后验证：

import cv2 as cv
print(cv.__version__)

打印出版本号且无 ModuleNotFoundError: No module named 'cv2' 即大功告成。若导入失败，最常见的原因是 2.4 节的探测块中 numpy 一行缺失（Python 绑定根本没被构建），或 packages path 指向的解释器与你当前使用的解释器不一致——对照 CMake 输出中的 Interpreter 路径确认即可。

深入：Python 绑定是如何被构建的

构建出的 cv2 并非独立代码，而是链接主库的扩展模块。从源码结构看，绑定逻辑集中在 modules/python 模块：python3/ 子目录包含 Python 3 绑定的生成与构建配置，src2/ 存放核心绑定源文件，bindings/ 则负责由 C++ 头文件声明自动生成 Python 绑定代码。这也解释了教程中一个常见疑问：Python 绑定随 make 一起编译，其可用功能面与 C++ 主线一致，因此教程强调“版本越新，Python API 支持越好”。

延伸阅读

• 官方推荐的 pip 安装路径（含虚拟环境与排错）：pip 安装教程
• C++ 源码编译完整 CMake 选项参考（教程中 @ref tutorial_linux_install 指向的页面）：Linux C++ 编译指南
• 其他发行版对照：Fedora 安装教程、Windows 安装教程

小结

维度	apt 预编译包	源码编译
命令复杂度	一条 apt-get	依赖安装 + CMake 四步
版本时效	受发行版软件源限制	始终最新
模块组合/自定义	不可控	完全可控
参与贡献	不支持	必需
最低工具链	随发行版	CMake ≥ 3.13，Python ≥ 3.2

掌握本教程后，读者可以在 Ubuntu 上完成 cv2 的快速安装，也能独立完成从源码构建到 make install 的完整链路，并理解 CMake 输出中 Python 3 探测块每一行的含义与对应源码位置。