opencv-python

保持OpenCV免费

OpenCV正在筹集资金以保持该库对所有人免费，我们需要整个社区的支持才能做到这一点。在Github上捐赠给OpenCV以表示您的支持。

OpenCV轮子版
- 安装和使用
常见问题
opencv-python文档

OpenCV轮子版

预构建的仅CPU的Python OpenCV包。

如果您希望从源代码编译绑定以启用额外模块（如CUDA），请查看手动构建部分。

安装和使用

如果您之前手动安装了OpenCV（即不是通过pip安装的），请在安装前删除它，以避免冲突。
确保您的pip版本是最新的（最低支持版本为19.3）：pip install --upgrade pip。使用pip -V检查版本。例如，Linux发行版通常附带非常旧的pip版本，这会导致许多意外问题，尤其是在使用manylinux格式时。
为您的环境选择正确的包：

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

a. 标准桌面环境包（Windows、macOS、几乎所有GNU/Linux发行版）
- 选项1 - 主模块包：pip install opencv-python
- 选项2 - 完整包（包含主模块和contrib/额外模块）：pip install opencv-contrib-python（查看OpenCV文档中的contrib/额外模块列表）
b. 服务器（无头）环境包（如Docker、云环境等），无GUI库依赖

这些包比上面的两个包更小，因为它们不包含任何GUI功能（未与Qt/其他GUI组件一起编译）。这意味着这些包避免了对X11库的重度依赖，因此您可以获得更小的Docker镜像。如果您不使用cv2.imshow等函数，或者您使用其他包（如PyQt）而不是OpenCV来创建GUI，则应始终使用这些包。
- 选项3 - 无头主模块包：pip install opencv-python-headless
- 选项4 - 无头完整包（包含主模块和contrib/额外模块）：pip install opencv-contrib-python-headless（查看OpenCV文档中的contrib/额外模块列表）
导入包：

import cv2

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

cv2.CascadeClassifier(cv2.data.haarcascades + "haarcascade_frontalface_default.xml")
阅读OpenCV文档
在提出新问题之前，请阅读下面的常见问题，并查看其他已经开放的问题。

常见问题

问：我是否需要单独安装OpenCV？

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

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

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

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

答：如果在Windows上导入失败，请确保您已安装Visual C++可再发行组件2015。如果您使用的Windows版本低于Windows 10，且未安装最新的系统更新，可能还需要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 vs. cv2）？

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

opencv-python的文档

该仓库的目标是为最常用的Python版本和平台提供打包每个新OpenCV发布版的方法。

CI构建过程

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

在Linux和MacOS构建中：获取我们编译所依赖的OpenCV可选C依赖项
检出仓库和子模块
- OpenCV作为子模块包含在内，当有新的OpenCV发布时，版本由维护者手动更新
- Contrib模块也作为子模块包含
从源代码中找出OpenCV版本
构建OpenCV
- 禁用测试，否则构建时间会大幅增加
- 每个构建组合有4个构建矩阵条目：带和不带contrib模块，带和不带GUI（无头）
- Linux构建在manylinux Docker容器（CentOS 5）中运行
- 源代码分发是构建矩阵中的单独条目
重新安排OpenCV的构建结果，添加我们的自定义文件并生成wheel
Linux和macOS的wheel分别用auditwheel和delocate进行转换
安装生成的wheel
测试Python是否可以导入该库并运行一些健全性检查
使用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环境外手动构建的更多信息，请参见下一节。

手动构建

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

克隆此仓库：git clone --recursive https://github.com/opencv/opencv-python.git
cd opencv-python
- 如果需要，可以使用git在opencv和opencv_contrib子模块中检出OpenCV的其他版本
如果需要，添加自定义Cmake标志，例如：export CMAKE_ARGS="-DSOME_FLAG=ON -DSOME_OTHER_FLAG=OFF"（在Windows中，根据命令行或PowerShell的不同，需要以不同方式设置环境变量）
通过ENABLE_CONTRIB和ENABLE_HEADLESS选择要构建的包类型：例如，如果想构建opencv-contrib-python，则export ENABLE_CONTRIB=1
运行pip wheel . --verbose。注意：确保使用最新版本的pip，pip wheel命令替代了旧的python setup.py bdist_wheel命令，后者不支持pyproject.toml。
- 根据你的硬件配置，这可能需要5分钟到2小时以上
Pip会在构建过程结束时打印新wheel的位置。如果使用旧的setup.py文件方法，wheel包将放在dist文件夹中。包准备就绪，你可以随意处理。
- 可选：在Linux上，如果需要最大程度的可移植性，可以使用某些manylinux镜像作为构建主机，并在构建后对wheel运行auditwheel
- 可选：在macOS上使用delocate（类似于auditwheel但适用于macOS）以提高可移植性

手动调试构建

要以未优化的调试模式构建opencv-python，需要稍微绕过正常流程。

通过pip安装scikit-build和numpy包。
运行命令python setup.py bdist_wheel --build-type=Debug。
使用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。如果你需要PyPI中没有源代码分发的OpenCV版本，请按照上述手动构建指南操作，而不是这个。

你也可以强制pip从源代码分发构建wheel。例如：

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

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

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