计算机视觉 / 系统课时

安装 OpenCV

安装 OpenCV

本课完成 OpenCV 的 Python 环境安装,并解决最常见的解释器不一致和安装包冲突问题。你将根据桌面或服务器环境选择正确版本,再通过导入、版本号和模块路径验证安装结果。

学习目标

  • 检查 Python 与 pip 是否指向同一环境
  • 区分桌面版、无界面版和扩展模块版本
  • 安装 OpenCV 并完成可重复的导入验证

安装前检查

OpenCV 的 Python 包通过 pip 安装,但实际使用的是当前 Python 解释器中的 cv2 模块。安装前应先确认 Python 和 pip 都能正常运行。

bash
python --version
python -m pip --version

预期输出

text
Python 3.<MINOR>.<PATCH>
pip <VERSION> from <PATH> (python 3.<MINOR>)

<MINOR>、<PATCH>、<VERSION> 和 <PATH> 会随本机环境变化。重点检查两条输出中的 Python 主版本和次版本是否一致。部分 Linux 或 macOS 环境需要将命令中的 python 替换为 python3。

建议在项目虚拟环境中安装依赖,避免系统 Python、其他项目和当前项目互相覆盖。执行安装与运行脚本时,应始终使用同一个解释器入口,例如统一使用 python -m pip,不要混用不同来源的 pip 命令。

选择正确的安装包

OpenCV 在 PyPI 中提供四个常用包。它们导入时都使用 import cv2,区别主要在于是否包含扩展模块和图形界面支持。

安装包 适用环境 特点
opencv-python 本地桌面开发 包含主要模块和窗口显示能力
opencv-python-headless 服务器、容器、后台任务 不包含 GUI 依赖,体积通常更小
opencv-contrib-python 需要额外算法的桌面项目 包含主要模块、扩展模块和 GUI
opencv-contrib-python-headless 需要额外算法的服务器项目 包含扩展模块,但不包含 GUI

同一个 Python 环境只应保留其中一个包。这些包都会提供名为 cv2 的模块,同时安装多个版本可能造成文件覆盖、模块来源不明确或升级后导入异常。

普通桌面学习环境优先选择 opencv-python。不调用 cv2.imshow 等窗口接口的服务器或 Docker 环境,优先选择 opencv-python-headless。只有明确需要扩展算法时,才选择带有 contrib 的版本。

安装并验证

下面以桌面版为例。先升级当前解释器对应的 pip,再安装 OpenCV,最后打印版本号和模块文件路径。

bash
python -m pip install --upgrade pip
python -m pip install opencv-python
python -c "import cv2; print('version=', cv2.__version__); print('module=', cv2.__file__)"

预期输出

text
version= 4.<MINOR>.<PATCH>
module= <PATH>/cv2<FILE_SUFFIX>

版本号和文件路径会因安装时间、操作系统和 Python 环境而不同。命令没有出现异常,并且 module 指向当前项目使用的环境路径,即表示 OpenCV 已经可以被该解释器加载。

服务器环境只需把安装包替换为无界面版本:python -m pip install opencv-python-headless。安装包名称发生变化后,Python 代码仍然使用 import cv2,不需要改成 import opencv_python_headless。

常见失败处理

出现 ModuleNotFoundError: No module named 'cv2' 时,通常不是包名错误,而是安装 OpenCV 的解释器与运行程序的解释器不同。先执行 python -m pip show opencv-python,再执行 python -c "import sys; print(sys.executable)",确认包信息和解释器路径属于同一环境。

如果同时安装过多个 OpenCV 包,应先使用 python -m pip uninstall 分别卸载 opencv-python、opencv-python-headless、opencv-contrib-python 和 opencv-contrib-python-headless,确认清理完成后只重新安装一个目标版本。

无界面服务器中调用 cv2.imshow 可能出现图形后端或显示服务错误。这不是图像处理功能失效,而是 headless 包刻意移除了窗口依赖。后台任务应使用 cv2.imwrite 保存结果;确实需要弹出窗口时,应改用非 headless 包并确保系统存在可用的桌面显示环境。

安装过程如果长时间停在下载阶段,可先检查网络、代理和 pip 镜像配置。不要随意从不可信网站下载名称相似的二进制包,以免引入版本不兼容或供应链风险。

验收标准

安装完成后,应同时满足三个条件:import cv2 不抛出异常,cv2.__version__ 能输出版本号,cv2.__file__ 指向预期的虚拟环境或 Python 安装目录。

如果项目需要窗口显示,还应在有桌面环境的机器上单独测试 cv2.imshow。如果项目只在服务器处理图片,则成功读取、转换并通过 cv2.imwrite 写出文件就足以完成验收。

本课总结

  • 使用 python -m pip 可以减少 pip 与 Python 解释器不一致的问题
  • 桌面环境选择普通版,服务器和容器通常选择 headless 版
  • 同一环境只保留一个 OpenCV 包,并通过版本号与模块路径验证安装

下一课预告

下一课将进入 OpenCV 的基本处理流程,学习读取图像、检查尺寸与通道、修改图像并将结果写入新文件。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

安装 OpenCV

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通