opencv-python-headless 4.10.0.84

保持OpenCV免费

OpenCV正在筹集资金以保持库对所有用户的免费，我们需要整个社区的支持来实现这一点。[在Github上捐赠给OpenCV](https://github.com/sponsors/opencv) 以展示您的支持。

• OpenCV on Wheels
  • 安装和使用
• 常见问题解答
• opencv-python的文档
  • CI构建过程
  • 手动构建
    • 手动调试构建
    • 源代码分发
  • 许可
  • 版本控制
  • 版本发布
  • 开发版本构建
  • Manylinux轮子
  • 支持的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. 在打开新问题之前，请阅读以下FAQ，并查看已打开的其他问题。

常见问题解答

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

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

Q: 使用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加载失败：找不到指定的模块。？

答：如果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绑定手动安装（site-packages中的cv2.so或cv2.pyd）。

问：函数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与cv2）？

答：opencv-python比cv2更容易让用户理解，并且使搜索引擎更容易找到该包。在旧版本的OpenCV中，旧接口的名称为cv，OpenCV开发者在创建绑定生成器时选择了cv2作为名称。为了与互联网上的不同类型的教程保持一致，保留了该导入名称。更改导入名称或行为可能会让习惯于使用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将生成的wheel文件安装到dist/文件夹中。

如果您想构建时生成所有编译器命令，以下组合的标志和环境变量已在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

如果您需要贡献模块或无头版本，只需更改软件包名称（前一个部分中的步骤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轮子

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

默认的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发行版的 support。

从版本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。Brew和大多数常用包已废弃对Mac OS 10.x的支持。