安装与配置

本页整理自官方「使用预构建二进制」教程与社区常见做法。兼容性要求：OpenCV >= 5.0、C++17、Python >= 3.6。

C++17+
编译标准（强制）: Python 3.6+
不再支持 Python 2: CMake 3.22+
官方教程推荐版本

pip 安装 Python 绑定（最快上手）

适合 Python 原型开发，无需编译。

# 稳定版
pip install opencv-python

# 含 contrib 额外模块
pip install opencv-contrib-python

# 无 GUI 支持（服务器/无显示环境）
pip install opencv-python-headless

验证 / 注意

python -c "import cv2; print(cv2.__version__)"

预构建二进制（C++ 项目）

通过安装器、apt/Homebrew/vcpkg 安装后，用 CMake 自动链接。

# CMakeLists.txt
cmake_minimum_required(VERSION 3.22)
project(OpenCV5_Local_Project)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(OpenCV 5.0 REQUIRED)
message(STATUS "Found OpenCV version: ${OpenCV_VERSION}")

add_executable(app main.cpp)
target_link_libraries(app PRIVATE ${OpenCV_LIBS})

# 构建运行
mkdir build && cd build
cmake ..
cmake --build .
./app

验证 / 注意

# 若 CMake 找不到安装位置：
cmake -DOpenCV_DIR=/path/to/opencv/build ..

g++ 直接编译（Linux / macOS）

单条命令，无需生成构建文件。

# 使用 pkg-config
g++ -std=c++17 main.cpp -o app \
  $(pkg-config --cflags --libs opencv5)

# 显式指定路径（自定义构建）
g++ -std=c++17 main.cpp -o app \
  -I/usr/local/include/opencv5 \
  -L/usr/local/lib \
  -lopencv_core -lopencv_imgcodecs \
  -lopencv_highgui -lopencv_imgproc

验证 / 注意

# 注意：5.0 已无 -lopencv_calib3d
# 请按需链接：-lopencv_geometry -lopencv_calib
#             -lopencv_stereo -lopencv_ptcloud

从源码构建

需要自定义模块、启用 CUDA/OpenVINO 等可选功能时使用。

git clone https://github.com/opencv/opencv.git
cd opencv && git checkout 5.0.0

# 可选：额外模块
git clone https://github.com/opencv/opencv_contrib.git

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTS=OFF \
  -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules \
  ..
cmake --build . --parallel

# 安装（Linux 默认 /usr/local）
sudo cmake --install .

验证 / 注意

cmake -LH | grep -i opencv  # 查看可用开关
# 常用开关：WITH_CUDA / WITH_OPENCL / BUILD_opencv_python3

移动端与平台包

Android Studio / CocoaPods / 系统包管理器。

# Ubuntu / Debian
sudo apt install libopencv-dev python3-opencv

# macOS
brew install opencv

# vcpkg (跨平台 C++)
vcpkg install opencv5

# Windows (vcpkg)
vcpkg install opencv5:x64-windows

验证 / 注意

pkg-config --modversion opencv5

平台速查表

平台	C++ 安装	Python	备注
Windows	官方预编译包 / vcpkg / 源码	pip install opencv-python	需 MSVC 2019+ 与 C++17
Ubuntu/Debian	apt install libopencv-dev	pip 或 apt python3-opencv	注意 apt 版本可能滞后于 5.0
Fedora/RHEL	dnf install opencv-devel	pip install opencv-python
macOS	brew install opencv	pip install opencv-python	Apple Silicon 原生支持
Android	SDK Manager 中的 OpenCV SDK / Maven	不适用	通过 Java/Kotlin 或 NDK 使用
iOS	OpenCV iOS framework	不适用	从源码或官方框架集成
浏览器	OpenCV.js（WASM）	不适用	opencvs.org / 构建脚本生成

常见问题排查

"OpenCV 5.0 requires C++17"

工具链回退到了旧标准。g++ 加 -std=c++17；CMake 在 find_package 之前设置 CMAKE_CXX_STANDARD 17。

CMake 提示找不到 package 配置文件

显式传入路径：cmake -DOpenCV_DIR=/path/to/opencv/build/ ..

链接 -lopencv_calib3d 失败

5.0 已将 calib3d 拆分为 geometry、calib、stereo、ptcloud，请链接对应新库。

Python import cv2 失败

自定义构建需设置 PYTHONPATH 指向 build/lib（或 build/lib/python3），再用 python -c "import cv2; print(cv2.__version__)" 验证。

运行时找不到动态库

Linux/macOS 设置 LD_LIBRARY_PATH / DYLD_LIBRARY_PATH；或配置 ldconfig 缓存；Windows 将 bin 目录加入 PATH。