opencv-python-headless 4.6.0.66

车轮上的 OpenCV

为 Python 预构建的仅限 CPU 的 OpenCV 包。

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

安装使用

1. 如果您安装了以前/其他手动安装（= 未通过pip）版本的 OpenCV（例如 Python 站点包根目录中的 cv2 模块），请在安装前将其删除以避免冲突。

2. 确保您的pip版本是最新的（19.3 是支持的最低版本）pip install --upgrade pip：. 使用 . 检查版本pip -V。例如，Linux 发行版通常带有非常旧的pip版本，这会导致很多意想不到的问题，尤其是在manylinux格式方面。

3. 为您的环境选择正确的包：

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

   一个。适用于标准桌面环境的软件包（Windows、macOS、几乎所有 GNU/Linux 发行版）

   • 选项 1 - 主要模块包：pip install opencv-python
   • 选项 2 - 完整包（包含主模块和 contrib/extra 模块）：（查看OpenCV 文档pip install opencv-contrib-python中的 contrib/extra 模块列表）

   湾。服务器（无头）环境（如 Docker、云环境等）的包，无 GUI 库依赖项

   这些包比上面的其他两个包要小，因为它们不包含任何 GUI 功能（未使用 Qt/其他 GUI 组件编译）。这意味着这些包避免了对 X11 库的重依赖链，因此您将拥有例如更小的 Docker 映像。如果您不使用cv2.imshowet al，则应始终使用这些软件包。或者您正在使用 OpenCV 之外的其他包（例如 PyQt）来创建您的 GUI。

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

4. 导入包：

   import cv2

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

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

5. 阅读OpenCV 文档

6. 在打开新问题之前，请阅读下面的常见问题解答并查看已经打开的其他问题。

经常问的问题

问：我还需要单独安装 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。pip install --upgrade pip

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

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

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

如果您有 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）。

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

答：存储库仅包含 OpenCV-Python 包构建脚本，而不包含 OpenCV 本身。OpenCV 的 Python 绑定是在官方 OpenCV 存储库中开发的，它是报告问题的最佳场所。在提交新的错误之前，请检查 {OpenCV wiki]( https://github.com/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）？

A：用户更容易理解，也opencv-python更cv2容易用搜索引擎找到包。cv2（旧 OpenCV 版本中的旧接口被命名为cv）是 OpenCV 开发人员在创建绑定生成器时选择的名称。这被保留为导入名称，以与互联网上不同类型的教程保持一致。更改导入名称或行为也会让习惯于import cv2.

opencv-python 的文档

这个存储库的目的是为最常用的 Python 版本和平台提供打包每个新OpenCV 版本的方法。

CI 构建过程

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

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

1. 签出存储库和子模块

   • OpenCV 包含在子模块中，当发布新的 OpenCV 版本时，维护人员会手动更新版本
   • Contrib 模块也作为子模块包含在内

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

3. 构建 OpenCV

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

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

5. Linux和macOS的轮子用auditwheel和delocate进行了相应的转换

6. 安装生成的轮子

7. 测试 Python 是否可以导入库并运行一些健全性检查

8. 使用 twine 将生成的轮子上传到 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 环境之外手动构建的更多信息，请参阅下一节。

手动构建

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

1. 克隆此存储库：git clone --recursive https://github.com/opencv/opencv-python.git
2. cd opencv-python
   • 如果需要，您可以使用在和子模块git中检出其他版本的 OpenCVopencvopencv_contrib
3. 如果需要，添加自定义 Cmake 标志，例如：（export CMAKE_ARGS="-DSOME_FLAG=ON -DSOME_OTHER_FLAG=OFF"在 Windows 中，您需要根据命令行或 PowerShell 设置不同的环境变量）
4. 选择您希望构建的包风格，ENABLE_CONTRIB并且ENABLE_HEADLESS：即export ENABLE_CONTRIB=1如果您希望构建opencv-contrib-python
5. 运行pip wheel . --verbose。注意：确保您拥有最新pip版本，该命令将替换不支持pip wheel的旧命令。 python setup.py bdist_wheelpyproject.toml
   • 这可能需要 5 分钟到 2 多个小时不等，具体取决于您的硬件
6. 您将在文件dist夹中拥有轮文件，您可以随心所欲地使用它
   • 可选：在 Linux 上，如果需要最大的可移植性，则使用一些manylinux映像作为构建主机并auditwheel在构建后运行轮子
   • 可选：在 macOS 上使用delocate（与 macOS 相同auditwheel但用于 macOS）以获得更好的可移植性

手动调试构建

为了构建opencv-python未优化的调试版本，您需要稍微避开正常过程。

1. 安装软件包scikit-build并numpy通过 pip。
2. 运行命令python setup.py bdist_wheel --build-type=Debug。
3. 将生成的 wheel 文件安装dist/在pip install dist/wheelname.whl.

如果您希望构建生成所有编译器命令，那么以下标志和环境变量的组合已经过测试，可以在 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 中的任何轮子不兼容，pip将尝试从源代码构建 OpenCV。如果您需要 PyPI 中没有作为源代码分发的 OpenCV 版本，请按照上面的手动构建指南而不是这个指南。

您还可以强制pip从源代码分发中构建轮子。一些例子：

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

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

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

许可

Opencv-python 包（此存储库中的脚本）在 MIT 许可下可用。

OpenCV 本身在Apache 2许可下可用。

第三方软件包许可证位于LICENSE-3RD-PARTY.txt。

所有车轮都附带LGPLv2.1许可的FFmpeg。

非无头 Linux 轮子随附有LGPLv3许可的Qt 5。

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

版本控制

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

发布

当一个新标签被推送到主分支时，发布并上传到 PyPI。这些标签区分包（这个 repo 可能有修改，但 OpenCV 版本保持不变）并且应该按顺序递增。在实践中，发布版本号如下所示：

cv_major.cv_minor.cv_revision.package_revision例如3.1.0.0

主分支遵循 OpenCV 主分支发布。3.4 分支遵循 OpenCV 3.4 错误修复版本。

开发构建

将构建此 repo 的 master 分支的每个提交。可能的构建工件使用本地版本标识符：

cv_major.cv_minor.cv_revision+git_hash_of_this_repo例如3.1.0+14a8d39

这些工件不能也不会上传到 PyPI。

Manylinux 轮子

Linux 轮子是使用manylinux2014 构建的。这些轮子对于大多数发行版（使用 GNU C 标准库）来说应该是开箱即用的，因为它们是针对旧版本的 glibc 构建的。

默认manylinux2014图像已通过一些 OpenCV 依赖项进行了扩展。有关详细信息，请参阅Docker 文件夹。

支持的 Python 版本

为官方支持的 Python 版本（不在 EOL 中）提供了与 Python 3.x 兼容的预构建轮子：

• 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 发行版的支持。