计算机视觉 / 系统课时
安装 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:
py -3 --version
py -3 -m pip --version预期输出:
Python <PYTHON_VERSION>
pip <PIP_VERSION> from <PATH> (python <PYTHON_MAJOR_MINOR>)macOS 或 Linux:
python3 --version
python3 -m pip --version预期输出:
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。
python -m pip install --upgrade pip
python -m pip install opencv-python
python -c "import cv2; print(cv2.__version__)"预期输出:
<OPENCV_VERSION><OPENCV_VERSION> 会随安装时的发布版本变化。不要在同一个环境同时安装 opencv-python 与 opencv-contrib-python,因为它们都提供同一个 cv2 命名空间,混装容易造成文件覆盖和导入冲突。
验证一次真实图像操作
只打印版本号只能证明模块能导入,还应执行一个最小 OpenCV 操作。下面创建一张 8×8 的三通道黑图,再用 cv2.cvtColor 转为灰度图;灰度结果应从三维数组变成二维数组。
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()))"预期输出:
<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,避免无用的图形界面依赖。