opencv-contrib-python-headless 4.10.0.84

保持OpenCV免费

OpenCV正在筹集资金以保持库对所有用户的免费，我们需要整个社区的支持来实现这一点。在Github上向OpenCV捐赠以显示您的支持。

• OpenCV on Wheels
  • 安装和使用
• 常见问题解答
• opencv-python文档
  • CI构建过程
  • 手动构建
    • 手动调试构建
    • 源代码发行版
  • 许可
  • 版本控制
  • 发布
  • 开发构建
  • Manylinux wheel
  • 支持的Python版本
  • 向下兼容性

OpenCV on Wheels

为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（检查来自OpenCV文档的contrib/extra模块列表）

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

   这些软件包比上面的两个软件包更小，因为它们不包含任何GUI功能（未与Qt/其他GUI组件编译）。这意味着这些软件包避免了X11库的复杂依赖链，您将获得更小的Docker镜像等。如果您不使用cv2.imshow等或使用其他软件包（如PyQt）而不是OpenCV创建GUI，则应始终使用这些软件包。

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

4. 导入软件包

   import cv2

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

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

5. 阅读OpenCV文档

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

常见问题解答

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

A：不需要，这些软件包是特殊的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+，可能也缺少media DLLs；请在服务器管理器中安装名为“Media Foundation”的功能。请注意，一些帖子建议安装“Windows Server Essentials Media Pack”，但这需要“Windows Server Essentials Experience”角色，而这个角色将深刻影响你的Windows Server配置（通过强制活动目录集成等）；所以只安装“Media Foundation”应该是一个更安全的选项。

如果上述方法没有帮助，请检查你是否使用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和官方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文件）

0. 在Linux和MacOS构建中：获取与OpenCV编译相关的可选C依赖项

1. 检出仓库和子模块

   • OpenCV作为子模块包含，版本由维护者手动更新，当发布新的OpenCV版本时
   • 贡献模块也作为子模块包含

2. 从源中查找OpenCV版本

3. 构建OpenCV

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

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

5. 使用auditwheel和delocate分别将Linux和macOS wheel转换

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以构建带有或不带有贡献模块和无头版本的版本
• 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，则设置export ENABLE_CONTRIB=1
5. 运行pip wheel . --verbose。注意：请确保您有最新的pip版本，pip wheel命令替换了旧的python setup.py bdist_wheel命令，该命令不支持pyproject.toml。
   • 这可能需要从5分钟到2小时以上，具体取决于您的硬件
6. Pip将在构建过程结束时打印新鲜wheel的位置。如果您使用带有setup.py文件的旧方法，wheel包将放置在dist文件夹中。包已准备好，您可以对其进行任何操作。
   • 可选：如果需要最大可移植性，在Linux中使用某些manylinux镜像作为构建宿主，并在构建后运行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。如果您需要 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 依赖项。

在慢速系统（如 Raspberry Pi）上，完整的构建可能需要几个小时。在 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 源代码中搜索版本信息，并将特定于此存储库的修订号添加到版本字符串中。它将版本信息保存到 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 wheel

Linux的wheel文件使用manylinux2014构建。由于它们针对旧版本的glibc构建，因此这些wheel文件应该适用于大多数使用GNU C标准库的发行版（distros）。

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

支持的Python版本

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

• 3.7
• 3.8
• 3.9
• 3.10
• 3.11
• 3.12

向下兼容性

从4.2.0和3.4.9版本开始，macOS Travis构建环境已更新到XCode 9.4。这一变化实际上取消了对于10.13之前macOS版本的支持。

从4.3.0和3.4.10版本开始，Linux构建环境从manylinux1更新到manylinux2014。这取消了对于旧Linux发行版的支持。

从版本4.7.0开始，Mac OS GitHub Actions构建环境已更新到版本11。对Mac OS 10.x的支持已弃用。参见https://github.com/actions/runner-images/issues/5583

从版本4.9.0开始，Mac OS GitHub Actions构建环境已更新到版本12。Mac OS 10.x的支持已由Brew和大多数使用的包弃用。