计算机视觉 / 系统课时
安装 OpenCV
安装 OpenCV
本课完成 OpenCV 的 Python 环境安装,并解决最常见的解释器不一致和安装包冲突问题。你将根据桌面或服务器环境选择正确版本,再通过导入、版本号和模块路径验证安装结果。
学习目标
- 检查 Python 与 pip 是否指向同一环境
- 区分桌面版、无界面版和扩展模块版本
- 安装 OpenCV 并完成可重复的导入验证
安装前检查
OpenCV 的 Python 包通过 pip 安装,但实际使用的是当前 Python 解释器中的 cv2 模块。安装前应先确认 Python 和 pip 都能正常运行。
python --version
python -m pip --version预期输出
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,最后打印版本号和模块文件路径。
python -m pip install --upgrade pip
python -m pip install opencv-python
python -c "import cv2; print('version=', cv2.__version__); print('module=', cv2.__file__)"预期输出
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 的基本处理流程,学习读取图像、检查尺寸与通道、修改图像并将结果写入新文件。