OpenCV Python 最流行的开源计算机视觉处理库

OpenCV 预编译包

为 Python 提供的预编译 CPU 版 OpenCV 包。

如需启用 CUDA 等额外模块，请查阅手动构建部分以从源码编译绑定。

安装与使用

1. 如果之前通过非 pip 方式手动安装了其他版本的 OpenCV（例如 Python 的 site-packages 根目录下有 cv2 模块），请在安装前将其移除，以避免冲突。
2. 确保你的 pip 版本是最新的（最低支持版本为 19.3）：pip install --upgrade pip。使用 pip -V 检查版本。例如，Linux 发行版通常附带的 pip 版本非常旧，这会导致许多意外问题，尤其是与 manylinux 格式相关的问题。

3. 为你的环境选择正确的包：

   共有四种不同的包（见下面的选项 1、2、3 和 4），你只能选择其中一种。不要在同一个环境中安装多个不同的包。没有插件架构：所有包都使用相同的命名空间（cv2）。如果你在同一个环境中安装了多个不同的包，请使用 pip uninstall 全部卸载，然后重新安装一个包。

   a. 标准桌面环境包（Windows、macOS、几乎任何 GNU/Linux 发行版）

   • 选项 1 - 主模块包：pip install opencv-python
   • 选项 2 - 完整包（包含主模块和 contrib/extra 模块）：pip install opencv-contrib-python（contrib/extra 模块列表请查阅 OpenCV 文档）

   b. 服务器（无头）环境包（如 Docker、云环境等），无 GUI 库依赖

   这些包比上述两个包更小，因为它们不包含任何 GUI 功能（未编译 Qt / 其他 GUI 组件）。这意味着这些包避免了与 X11 库的繁重依赖链，例如，你的 Docker 镜像会更小。如果你不使用 cv2.imshow 等函数，或者使用 OpenCV 以外的其他包（如 PyQt）来创建 GUI，则应始终使用这些包。

   • 选项 3 - 无头主模块包：pip install opencv-python-headless
   • 选项 4 - 无头完整包（包含主模块和 contrib/extra 模块）：pip install opencv-contrib-python-headless（contrib/extra 模块列表请查阅 OpenCV 文档）

4. 导入包：

   import cv2

   所有包都包含 Haar 级联文件。cv2.data.haarcascades 可用作数据文件夹的快捷方式。例如：

   cv2.CascadeClassifier(cv2.data.haarcascades + "haarcascade_frontalface_default.xml")

5. 阅读 OpenCV 文档

6. 在提出新问题前，请先阅读下面的常见问题解答，并查看其他已开放的问题。

常见问题解答

问：我需要单独安装 OpenCV 吗？

答：不需要，这些包是特殊的 wheel 二进制包，已经包含了静态构建的 OpenCV 二进制文件。

问：Pip 安装失败，提示 ModuleNotFoundError: No module named 'skbuild'？

从 opencv-python 版本 4.3.0.* 开始，manylinux1 wheels 被 manylinux2014 wheels 取代。如果你的 pip 版本太旧，它会尝试使用 4.3.0.38 版本中引入的新源码发行版来手动构建 OpenCV，因为它不知道如何安装 manylinux2014 wheels。然而，源码构建也会因为 pip 版本太旧而失败，因为它无法理解 pyproject.toml 中的构建依赖。要使用新的 manylinux2014 预构建 wheels（或从源码构建），你的 pip 版本必须 >= 19.3。请使用 pip install --upgrade pip 升级 pip。

问：在 Windows 上导入失败：ImportError: DLL load failed: The specified module could not be found.？

答：如果在 Windows 上导入失败，请确保已安装 Visual C++ redistributable 2015。如果你使用的是早于 Windows 10 的 Windows 版本且未安装最新的系统更新，可能还需要 Universal C Runtime。

Windows N 和 KN 版本不包含 OpenCV 所需的 Media Feature Pack。如果你使用的是 Windows N 或 KN 版本，请同时安装 Windows Media Feature Pack。

如果你有 Windows Server 2012+，媒体 DLL 可能也缺失；请在服务器管理器中安装名为 "Media Foundation" 的功能。注意，有些帖子建议安装 "Windows Server Essentials Media Pack"，但这需要 "Windows Server Essentials Experience" 角色，该角色会严重影响你的 Windows Server 配置（例如强制集成活动目录等）；因此仅安装 "Media Foundation" 应该是更安全的选择。

如果以上方法无效，请检查你是否在使用 Anaconda。旧版 Anaconda 存在导致此错误的 bug，手动修复方法请参见 此问题。

如果你在检查了所有之前的解决方案后仍然遇到错误，请下载 Dependencies 并用它打开 cv2.pyd 文件（通常位于 C:\Users\username\AppData\Local\Programs\Python\PythonXX\Lib\site-packages\cv2）来调试缺失的 DLL 问题。

问：我有其他导入错误？

答：确保你已经移除了旧的手动安装的 OpenCV Python 绑定（site-packages 中的 cv2.so 或 cv2.pyd）。

问：函数 foo() 或方法 bar() 返回错误结果、抛出异常或使解释器崩溃。我该怎么办？

答：此仓库仅包含 OpenCV-Python 包的构建脚本，不包含 OpenCV 本身。OpenCV 的 Python 绑定在官方 OpenCV 仓库中开发，那里是报告问题的最佳场所。在提交新 bug 之前，也请查看 OpenCV wiki 和 官方 OpenCV 论坛。

问：为什么这些包不包含非免费算法？

答：非免费算法（如 SURF）未包含在这些包中，因为它们受专利保护/非免费，因此不能作为构建好的二进制文件分发。请注意，由于专利过期，自 OpenCV 4.3.0 和 3.4.10 版本起，SIFT 已包含在构建中。更多信息请参见此问题：https://github.com/skvark/opencv-python/issues/126

问：为什么包名和导入名不同（opencv-python 对比 cv2）？

答：对用户来说，opencv-python 比 cv2 更容易理解，也更容易通过搜索引擎找到该包。cv2（旧版 OpenCV 中的旧接口名为 cv）是 OpenCV 开发者在创建绑定生成器时选择的名称。保持此导入名称是为了与互联网上各种教程保持一致。更改导入名称或行为也会让习惯了 import cv2 的有经验用户感到困惑。

opencv-python 文档

本仓库旨在为最常用的 Python 版本和平台打包每个新的 OpenCV 发布版本。

CI 构建流程

该项目结构类似于一个标准的 Python 包，带有标准的 setup.py 文件。
构建矩阵中单个条目的构建流程如下（例如，参见 .github/workflows/build_wheels_linux.yml 文件）：

0. 在 Linux 和 MacOS 构建中：获取我们编译所依赖的 OpenCV 可选 C 依赖项
1. 检出仓库和子模块
   • OpenCV 作为子模块包含，其版本由维护者在发布新 OpenCV 版本时手动更新
   • Contrib 模块也作为子模块包含
2. 从源码中查找 OpenCV 版本
3. 构建 OpenCV
   • 禁用测试，否则构建时间会增加太多
   • 每个构建组合有 4 个构建矩阵条目：包含和不包含 contrib 模块，包含和不包含 GUI（无头）
   • Linux 构建在 manylinux Docker 容器（CentOS 5）中运行
   • 源码发行版是构建矩阵中的独立条目
4. 重新整理 OpenCV 的构建结果，添加我们的自定义文件并生成 wheel
5. Linux 和 macOS wheels 分别使用 auditwheel 和 delocate 进行处理
6. 安装生成的 wheel
7. 测试 Python 是否可以导入库并运行一些完整性检查
8. 使用 twine 将生成的 wheel 上传到 PyPI（仅在发布构建中）

步骤 1-4 由 pip wheel 处理。

构建可以通过环境变量进行自定义。除了 OpenCV 构建接受的任何变量外，我们还识别：

• CI_BUILD。设置为 1 以模拟 CI 环境构建行为。仅在 CI 构建中使用，用于在 setup.py 中强制启用某些构建标志。除非你知道自己在做什么，否则不要使用此变量。
• ENABLE_CONTRIB 和 ENABLE_HEADLESS。设置为 1 以构建 contrib 和/或无头版本。
• ENABLE_JAVA。设置为 1 以启用 Java 客户端构建。默认禁用。
• CMAKE_ARGS。OpenCV CMake 调用的额外参数。你可以使用此变量进行自定义构建。

有关在 CI 环境外进行手动构建的更多信息，请参见下一节。

手动构建

如果预构建 wheels 中未启用某些依赖项，你也可以在本地运行构建以创建自定义 wheel。

1. 克隆此仓库：git clone --recursive https://github.com/opencv/opencv-python.git
2. cd opencv-python
   • 如果需要，你可以使用 git 在 opencv 和 opencv_contrib 子模块中检出其他版本的 OpenCV
3. 如果需要，添加自定义 Cmake 标志，例如：export CMAKE_ARGS="-DSOME_FLAG=ON -DSOME_OTHER_FLAG=OFF"（在 Windows 上，根据命令行或 PowerShell 的不同，你需要以不同方式设置环境变量）
4. 使用 ENABLE_CONTRIB 和 ENABLE_HEADLESS 选择要构建的包风格：例如，如果你希望构建 opencv-contrib-python，则 export ENABLE_CONTRIB=1
5. 运行 pip wheel . --verbose。注意：确保你有最新的 pip 版本，pip wheel 命令取代了旧的 python setup.py bdist_wheel 命令，后者不支持 pyproject.toml。
   • 根据你的硬件，这可能需要 5 分钟到超过 2 小时不等
6. 你将在 dist 文件夹中获得 wheel 文件，你可以随意处理它
   • 可选：在 Linux 上，如果需要最大可移植性，可以使用一些 manylinux 镜像作为构建主机，并在构建后对 wheel 运行 auditwheel
   • 可选：在 macOS 上，使用 delocate（与 auditwheel 类似，但用于 macOS）以获得更好的可移植性

手动调试构建

为了以非优化的调试模式构建 opencv-python，你需要稍微绕开正常流程。

1. 通过 pip 安装 scikit-build 和 numpy 包。
2. 运行命令 python setup.py bdist_wheel --build-type=Debug。
3. 使用 pip install dist/wheelname.whl 安装 dist/ 文件夹中生成的 wheel 文件。

如果你希望构建过程产生所有编译器命令，那么以下标志和环境变量的组合在 Linux 上测试有效：

export CMAKE_ARGS='-DCMAKE_VERBOSE_MAKEFILE=ON'
export VERBOSE=1

python3 setup.py bdist_wheel --build-type=Debug

更多讨论请参见此问题：https://github.com/opencv/opencv-python/issues/424

源码发行版

自 OpenCV 版本 4.3.0 起，PyPI 中也提供了源码发行版。这意味着如果你的系统与 PyPI 中的任何 wheel 都不兼容，pip 将尝试从源码构建 OpenCV。如果你需要的 OpenCV 版本在 PyPI 中没有作为源码发行版提供，请遵循上述手动构建指南，而不是此方法。

你也可以强制 pip 从源码发行版构建 wheels。一些示例：

• pip install --no-binary opencv-python opencv-python
• pip install --no-binary :all: opencv-python

如果你需要 contrib 模块或无头版本，只需更改包名（上一节的步骤 4 不需要）。但是，任何额外的 CMake 标志都可以通过环境变量提供，如手动构建部分步骤 3 所述。如果未提供任何标志，OpenCV 的 CMake 脚本将尝试查找并启用任何合适的依赖项。无头发行版具有硬编码的 CMake 标志，用于禁用所有可能的 GUI 依赖项。

在 Raspberry Pi 等慢速系统上，完整构建可能需要几个小时。在 8 核 Ryzen 7 3700X 上，构建大约需要 6 分钟。

许可

Opencv-python 包（此仓库中的脚本）遵循 MIT 许可证。

OpenCV 本身遵循 Apache 2 许可证。

第三方包许可证位于 LICENSE-3RD-PARTY.txt。

所有 wheels 都附带遵循 LGPLv2.1 许可的 FFmpeg。

非无头 Linux wheels 附带遵循 LGPLv3 许可的 Qt 5。

这些包还包括其他二进制文件。完整的许可证列表可以在 LICENSE-3RD-PARTY.txt 中找到。

版本控制

find_version.py 脚本从 OpenCV 源码中搜索版本信息，并附加一个特定于此仓库的修订号到版本字符串。它将版本信息以及一些其他标志保存到 cv2 下的 version.py 文件中。

发布

当向 master 分支推送新标签时，会创建发布并上传到 PyPI。这些标签区分包（此仓库可能有修改但 OpenCV 版本保持不变）并且应该按顺序递增。实际上，发布版本号看起来像这样：

cv_major.cv_minor.cv_revision.package_revision 例如 3.1.0.0

master 分支遵循 OpenCV master 分支的发布。3.4 分支遵循 OpenCV 3.4 的错误修复发布。

开发构建

此仓库 master 分支的每次提交都会被构建。可能的构建产物使用本地版本标识符：

cv_major.cv_minor.cv_revision+git_hash_of_this_repo 例如 3.1.0+14a8d39

这些产物不能也不会被上传到 PyPI。

Manylinux wheels

Linux wheels 使用 manylinux2014 构建。这些 wheels 应该可以在大多数使用 GNU C 标准库的发行版中开箱即用，因为它们针对旧版本的 glibc 构建。

默认的 manylinux2014 镜像已扩展了一些 OpenCV 依赖项。更多信息请参见 Docker 文件夹。

支持的 Python 版本

为官方支持的 Python 版本（非 EOL）提供了 Python 3.x 兼容的预构建 wheels：

• 3.6
• 3.7
• 3.8
• 3.9
• 3.10

向后兼容性

从 4.2.0 和 3.4.9 构建开始，macOS Travis 构建环境更新为 XCode 9.4。此更改实际上放弃了对早于 10.13 的 macOS 版本的支持。

从 4.3.0 和 3.4.10 构建开始，Linux 构建环境从 manylinux1 更新为 manylinux2014。这放弃了对旧 Linux 发行版的支持。