计算机视觉 / 系统课时

安装 Python 与 OpenCV

安装 Python 与 OpenCV

这一课完成一套可验证的 Python 与 OpenCV 安装:先确认解释器和 pip 可用,再安装正确的 OpenCV wheel,最后用一次真实图像转换检查 cv2 能否正常执行,而不是只看安装命令是否结束。

学习目标

  • 确认 Python 3 与 pip 指向可用的解释器。
  • 根据桌面或无界面环境选择正确的 OpenCV Python 包。
  • 用版本号和一次颜色转换验证 OpenCV 已真正运行。

检查 Python 与 pip

课程练习建议使用 CPython 3.12 或 3.13。Windows 可优先使用 Python Launcher;macOS 与 Linux 常见命令是 python3。不要只执行 pip,而要通过解释器调用 -m pip,这样能减少“包装到了另一个 Python”这类路径错误。

Windows PowerShell:

powershell
py -3 --version
py -3 -m pip --version

预期输出:

text
Python <PYTHON_VERSION>
pip <PIP_VERSION> from <PATH> (python <PYTHON_MAJOR_MINOR>)

macOS 或 Linux:

bash
python3 --version
python3 -m pip --version

预期输出:

text
Python <PYTHON_VERSION>
pip <PIP_VERSION> from <PATH> (python <PYTHON_MAJOR_MINOR>)

如果第一条命令就提示找不到 Python,应先完成 Python 3 安装并重新打开终端;如果只有 pip 不可用,可尝试 python -m ensurepip --upgrade,再重新检查。

安装正确的 OpenCV 包

PyPI 上的 OpenCV wheel 使用 cv2 作为导入名,同一环境只应选择下面一种包。普通桌面课程使用 opencv-python;只有确实需要 contrib 扩展模块时才改用 contrib 版本,服务器没有窗口显示需求时使用 headless 版本。

包名 适用场景
opencv-python 桌面学习、需要常用 OpenCV 模块与 GUI 功能
opencv-contrib-python 桌面环境,并需要 contrib/extra 模块
opencv-python-headless Docker、服务器、CI,不使用 cv2.imshow
opencv-contrib-python-headless 无界面环境,同时需要 contrib/extra 模块

下面以标准桌面包为例。若系统中 python 不是目标解释器,请替换成前一节验证过的 py -3 或 python3。

bash
python -m pip install --upgrade pip
python -m pip install opencv-python
python -c "import cv2; print(cv2.__version__)"

预期输出:

text
<OPENCV_VERSION>

<OPENCV_VERSION> 会随安装时的发布版本变化。不要在同一个环境同时安装 opencv-python 与 opencv-contrib-python,因为它们都提供同一个 cv2 命名空间,混装容易造成文件覆盖和导入冲突。

验证一次真实图像操作

只打印版本号只能证明模块能导入,还应执行一个最小 OpenCV 操作。下面创建一张 8×8 的三通道黑图,再用 cv2.cvtColor 转为灰度图;灰度结果应从三维数组变成二维数组。

bash
python -c "import cv2, numpy as np; img=np.zeros((8,8,3),dtype=np.uint8); gray=cv2.cvtColor(img,cv2.COLOR_BGR2GRAY); print(cv2.__version__); print(gray.shape); print(int(gray.sum()))"

预期输出:

text
<OPENCV_VERSION>
(8, 8)
0

看到 (8, 8) 和 0 表示 NumPy 数组已被 OpenCV 正常处理。这里不调用窗口显示函数,因此即使远程终端没有桌面,也能完成基础运行验证。

处理常见安装失败

出现 ModuleNotFoundError: No module named 'cv2' 时,先比较 python -m pip --version 与 python -c "import sys; print(sys.executable)" 指向的路径;二者应属于同一个 Python。若包安装在别的解释器下,应使用当前解释器重新执行 python -m pip install opencv-python。

如果安装过程开始长时间编译 OpenCV,而不是下载 wheel,先升级 pip,再重试。Windows 出现 DLL load failed 时,应优先检查系统运行库以及是否残留手工复制的旧 cv2.pyd;Linux 服务器若不需要 GUI,可改用 opencv-python-headless,避免无用的图形界面依赖。

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

目录与阅读设置

阅读设置

17

记录一个想法

安装 Python 与 OpenCV

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

登录哪都通