2、OpenCV环境搭建：Windows/Linux/Mac下OpenCV的安装、虚拟环境配置与版本管理

说实话，很多初学者一上来就急着写代码，结果卡在环境搭建上半天出不来。我见过太多人因为OpenCV版本冲突、Python环境混乱，折腾一整天还没跑通第一个demo。所以这一章，咱们先把地基打牢。

我个人习惯用虚拟环境来管理项目依赖。为什么呢？你想想看，一个项目用OpenCV 4.5，另一个项目用OpenCV 4.8，要是全装到系统Python里，迟早要打架。虚拟环境就是给每个项目一个独立的小房间，互不干扰。

2.1 虚拟环境：先把这个搞明白

虚拟环境说白了就是一个隔离的Python运行环境。每个虚拟环境有自己的Python解释器、pip和第三方库。你在里面装什么都不会影响到系统全局。

我推荐用 venv 或者 conda。如果你只是做OpenCV相关的视觉项目，venv 就够用了。但如果你还要搞深度学习（比如用PyTorch、TensorFlow），那 conda 会更省心，因为它连CUDA、cuDNN这些底层库都能帮你管。

我的建议： 新手先用 venv，轻量、简单。等后面要搞GPU加速了，再切到 conda 也不迟。

2.2 Windows下安装OpenCV

Windows用户最多，坑也最多。我当年第一次装OpenCV，直接 pip install opencv-python 就完事了，结果发现 cv2.imshow() 弹不出窗口。后来才知道，Windows上需要装带GUI支持的版本。

具体步骤：

  1. 安装Python：去官网下载Python 3.8~3.11版本（别用最新的3.12，有些库还没适配）。安装时记得勾选「Add Python to PATH」。
  2. 创建虚拟环境：打开命令行，到你项目目录下执行：
python -m venv opencv_env
opencv_env\Scripts\activate

看到命令行前面多了 (opencv_env) 就说明激活成功了。

  1. 安装OpenCV：
pip install opencv-python
pip install opencv-contrib-python  # 包含额外模块，比如SIFT、SURF
注意： 如果你只需要基础功能，装 opencv-python 就够了。opencv-contrib-python 包含了非自由算法，体积更大。我一般两个都装，省得后面用到某个功能时发现没有。
  1. 验证安装：
python -c "import cv2; print(cv2.__version__)"

如果输出了版本号，比如 4.8.1，那就成了。

2.3 Linux下安装OpenCV

Linux下装OpenCV，我建议用系统包管理器。Ubuntu/Debian用户直接：

sudo apt update
sudo apt install python3-opencv

但这样装的是系统级的，版本可能比较老。如果你想用最新版，还是走pip路线：

python3 -m venv opencv_env
source opencv_env/bin/activate
pip install opencv-python

嗯，这里要注意：Linux下如果要用摄像头，记得把用户加到 video 组：

sudo usermod -a -G video $USER

然后注销重新登录。不然你调用 cv2.VideoCapture(0) 时会报权限错误。我曾经在这个坑里爬了半小时...

2.4 Mac下安装OpenCV

Mac用户相对省心一些。用Homebrew可以装系统级OpenCV：

brew install opencv

但同样，我推荐用虚拟环境 + pip：

python3 -m venv opencv_env
source opencv_env/bin/activate
pip install opencv-python

Mac上有个常见问题：如果你用的是M1/M2芯片，有些OpenCV版本可能不支持。我建议用Python 3.9或3.10，配合OpenCV 4.6以上版本，兼容性最好。

2.5 版本管理：别让版本坑了你

为什么要单独讲版本管理？因为OpenCV不同版本之间API有变化。比如 cv2.findContours() 在OpenCV 3和4中返回值不一样。你从网上抄一段代码，很可能因为版本不对跑不起来。

我的做法是：

  • 在项目根目录放一个 requirements.txt，固定版本号：
opencv-python==4.8.1.78
opencv-contrib-python==4.8.1.78
numpy==1.24.3
  • 别人拿到项目后，直接 pip install -r requirements.txt 就能复现环境。
核心原则： 永远不要用 pip install opencv-python 而不指定版本。你今天是4.8，明天可能就变成4.9了，API一变，代码就炸。

2.6 多版本OpenCV共存

有时候你需要在不同项目里用不同版本的OpenCV。虚拟环境就是干这个的：

# 项目A：用OpenCV 4.5
python -m venv projectA_env
pip install opencv-python==4.5.5.64

# 项目B：用OpenCV 4.8
python -m venv projectB_env
pip install opencv-python==4.8.1.78

两个环境互不干扰。你激活哪个环境，就用哪个版本的OpenCV。

2.7 验证环境是否正常

装完之后，我习惯跑一个小脚本验证一下：

import cv2
import numpy as np

# 检查版本
print(f"OpenCV版本: {cv2.__version__}")

# 检查是否支持GUI
img = np.zeros((100, 100, 3), dtype=np.uint8)
cv2.imshow("test", img)
cv2.waitKey(1000)
cv2.destroyAllWindows()

# 检查摄像头
cap = cv2.VideoCapture(0)
if cap.isOpened():
    print("摄像头可用")
    cap.release()
else:
    print("摄像头不可用，检查权限或驱动")

如果GUI窗口能正常显示，摄像头也能打开，那环境就彻底搞定了。

避坑指南： 我曾经在服务器上装OpenCV，没有显示器，一调用 cv2.imshow() 就报错。后来才知道，服务器上要用 cv2.IMREAD_UNCHANGED 读图，然后用 cv2.imwrite() 保存到文件来验证。没有GUI的环境，就别折腾显示窗口了。

2.8 总结一下

环境搭建这事儿，说难不难，说简单也容易踩坑。核心就三点：

  • 用虚拟环境：每个项目独立，互不污染
  • 固定版本号：写在 requirements.txt 里，方便复现
  • 验证要全面：版本、GUI、摄像头，三步走完才算完

下一章咱们就开始真正接触OpenCV的图像读写操作了。环境搭好了，后面就顺畅了。

← 上一章 📖 返回目录 下一章 →