opencv-python-headless-rolling 5.0.0.20221015

OpenCV on Wheels

为Python预构建的仅CPU OpenCV软件包。

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

安装和使用

1. 如果您已安装先前的/其他手动安装的（=不是通过安装）的OpenCV版本（例如，Python的site-packages根目录中的cv2模块），请在安装之前将其删除，以避免冲突。

2. 确保您的pip版本是最新的（19.3是最小支持版本）：pip install --upgrade pip。使用检查版本。例如，Linux发行版通常附带的pip版本非常旧，这会导致许多意外问题，尤其是在格式中。

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等或使用其他软件包（如 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. 在提交新问题之前，请阅读下面的常见问题解答并查看已经打开的其他问题。

常见问题解答

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

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

Q：使用pip install失败，显示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。

Q：在 Windows 上导入失败：显示ImportError: DLL load failed: The specified module could not be found.错误？

A：如果导入在 Windows 上失败，请确保您已安装Visual C++ redistributable 2015。如果您使用的是比 Windows 10 更旧的 Windows 版本，并且未安装最新的系统更新，则可能还需要通用 C 运行时。

Windows N 和 KN 版本不包括 OpenCV 所需的媒体功能包。如果您使用的是 Windows N 或 KN 版本，请还安装Windows 媒体功能包。

如果您使用的是Windows Server 2012及以上版本，媒体DLL可能也丢失了；请在服务器管理器中安装名为“媒体基础”的功能。请注意，一些帖子建议安装“Windows Server Essentials Media Pack”，但此包需要“Windows Server Essentials Experience”角色，而这个角色将深刻影响您的Windows Server配置（通过强制活动目录集成等）；因此，仅安装“媒体基础”应该是一个更安全的选择。

如果上述方法没有帮助，请检查您是否使用Anaconda。旧版本的Anaconda存在一个错误，会导致错误，请参阅此问题以获取手动修复方法。

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

问：我有一些其他导入错误吗？

答：请确保您已删除OpenCV Python绑定（cv2.so或cv2.pyd在site-packages中的旧手动安装）。

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

答：此存储库仅包含OpenCV-Python包构建脚本，但不包含OpenCV本身。OpenCV的Python绑定是在官方OpenCV存储库中开发的，因此这是报告问题的最佳位置。在提交新错误之前，请检查{OpenCV wiki}[https://github.com/opencv/opencv/wiki]和官方OpenCV论坛。

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

答：由于这些非免费算法（如SURF）受专利保护/非免费，因此不能作为构建的二进制文件分发，因此不包括在这些包中。请注意，由于专利已到期，SIFT从OpenCV版本4.3.0和3.4.10开始已包含在构建中。有关更多信息，请参阅此问题：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版本时
   • 贡献模块也作为子模块包含在内

2. 从源代码中查找OpenCV版本

3. 构建OpenCV

   • 禁用了测试，否则构建时间会增加太多
   • 对于每个构建组合有4个构建矩阵条目：有和没有贡献模块，有和没有GUI（无头）
   • Linux构建在许多Linux Docker容器（CentOS 5）中运行
   • 源代码分发是构建矩阵中的单独条目

4. 重新排列OpenCV的构建结果，添加我们的自定义文件并生成wheel

5. Linux和macOS wheel分别通过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环境之外的手动构建的更多信息，请参阅下一节。

手动构建

如果某些依赖项在预构建的wheel中未启用，您还可以在本地运行构建以创建自定义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，则将ENABLE_CONTRIB设置为1
5. 运行pip wheel . --verbose。注意：确保您有最新的pip版本，pip wheel命令替换了旧的python setup.py bdist_wheel命令，该命令不支持pyproject.toml。
   • 这可能会花费从5分钟到2小时以上的时间，具体取决于您的硬件
6. 您将在dist文件夹中找到wheel文件，您可以对其进行任何操作
   • 可选：在Linux上，如果需要最大可移植性，请使用一些manylinux镜像作为构建主机，并在构建后运行auditwheel对wheel进行操作
   • 可选：在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。如果您需要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分钟。

许可证

OpenCV-python软件包（本存储库中的脚本）在MIT许可证下提供。

OpenCV本身在Apache 2许可证下提供。

第三方软件包的许可证在LICENSE-3RD-PARTY.txt中。

所有wheel都附带FFmpeg，许可证为LGPLv2.1。

非无头Linux wheel附带Qt 5，许可证为LGPLv3。

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

版本控制

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

发布

当将新标签推送到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 wheel

Linux wheel使用manylinux2014构建。由于它们针对旧的glibc版本进行构建，因此这些wheel应该可以在大多数使用GNU C标准库的distros（distros）中直接使用。

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

支持的Python版本

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

• 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发行版的兼容性。