opencv-python 4.10.0.84

保持OpenCV免费

OpenCV正在筹集资金以保持库对所有用户的免费状态，我们需要整个社区的支持来实现这一目标。请通过在Github上捐赠给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（检查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 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。

问：在 Windows 上导入失败：ImportError: DLL 加载失败：指定的模块未找到。?

答：如果在 Windows 上导入失败，请确保已安装 Visual C++ redistributable 2015。如果你使用的 Windows 版本比 Windows 10 旧，并且尚未安装最新系统更新，可能还需要 通用 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 有一个会导致错误的 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 存储库中开发的，因此报告问题最好的地方是那里。在提交新错误之前，请先检查 OpenCV wiki 和 官方 OpenCV 论坛。

问：为什么包中不包含非自由算法？

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

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

A：用户更易于理解 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 以构建贡献模块和/或无头版本
• 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会在构建过程结束时打印新的位置。如果您使用带有setup.py文件的旧方法，wheel包将放置在dist文件夹中。包已准备好，您可以随意处理。
   • 可选：在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

如果您需要贡献模块或无头版本，只需更改包名（上一节中的步骤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许可证。

非无头Linuxwheel包含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 wheels使用manylinux2014构建。由于它们针对旧版本的glibc进行构建，因此这些wheels应该适用于大多数使用GNU C标准库的distros（分发版）。

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

支持的Python版本

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

• 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。已通过Brew和大多数使用的软件包弃用Mac OS 10.x支持。