python opencv xiezai-杰瑞科技汇

“如何下载和安装 Python OpenCV？”

（图片来源网络，侵删）

下面我为您提供一份非常详细、图文并茂的教程，涵盖了在 Windows 和 macOS 系统上的完整流程,以及后续的验证和常见问题解决方法。

核心概念：OpenCV-Python vs. OpenCV Contrib

在开始之前,需要了解两个重要的包：

opencv-python: 这是 OpenCV 的核心包，包含了最常用、最稳定的功能，对于绝大多数用户来说,这个包已经足够了。
opencv-contrib-python: 这个包除了包含核心功能外，还包含了 "contrib" 模块，这些模块是一些实验性、新功能或特定领域（如人脸识别、3D重建）的算法，如果你需要这些高级功能,就应该安装这个包。

注意：opencv-python 和 opencv-contrib-python 不能同时安装，它们是互斥的,请根据你的需求选择其一。

第一步：安装 Python

OpenCV 是一个 Python 库，所以你需要先安装 Python。

（图片来源网络，侵删）

访问官网：打开浏览器，访问 Python 官方网站。
下载安装包：网站会自动检测你的操作系统并提供最新的稳定版下载，点击 "Download Python X.X.X" 按钮。
运行安装程序：
- Windows: 双击下载的 .exe 文件。
- macOS: 双击下载的 .pkg 文件。
关键步骤：添加到环境变量：
（图片来源网络，侵删）
- 在 Windows 安装程序的第一个界面，务必勾选 "Add Python to PATH" 或 "Add python.exe to PATH" 这个选项，这会让你后续在命令行中直接使用 python 命令。
- 在 macOS 中,安装程序通常会自动配置好路径。
验证安装：打开命令行工具（Windows 的 cmd 或 PowerShell，macOS 的 Terminal）,输入以下命令：
```
python --version
```
如果能看到 Python 的版本号（如 Python 3.11.4），说明 Python 安装成功。

第二步：使用 pip 下载并安装 OpenCV

pip 是 Python 的官方包管理工具，用它来安装 OpenCV 是最简单、最推荐的方式。

打开命令行工具：
- Windows: 按 Win + R，输入 cmd 或 powershell,然后回车。
- macOS: 在“应用程序” -> “实用工具” 中找到“终端”（Terminal）并打开。
执行安装命令：在命令行中,输入以下命令之一并按回车。
- 安装核心版 (推荐新手)：
```
pip install opencv-python
```
- 安装包含扩展模块的完整版 (如果你需要高级功能)：
```
pip install opencv-contrib-python
```

安装过程说明：

命令执行后，pip 会自动从 PyPI (Python Package Index) 下载 OpenCV 包及其所有依赖项（如 numpy）。
你会看到一个进度条，显示下载和安装的进度，这个过程可能需要几分钟，具体取决于你的网络速度和 OpenCV 包的大小（opencv-contrib-python 会比 opencv-python 大一些）。

第三步：验证安装

安装完成后，最重要的一步是验证 OpenCV 是否能正常导入和使用。

在命令行中测试：在同一个命令行窗口中，输入 python 进入 Python 交互式环境,然后依次执行以下命令：
```
# 导入 cv2 模块
import cv2
# 打印 OpenCV 的版本号
print(cv2.__version__)
```
如果一切正常，你会看到类似下面这样的输出,这表示安装成功！
```
8.1.78
>>>
```

在代码编辑器中测试 (推荐)：创建一个名为 test_opencv.py 的文件，将以下代码复制进去,然后运行它。

# test_opencv.py
import cv2
# 打印 OpenCV 版本
print(f"OpenCV 版本: {cv2.__version__}")
# 尝试读取一张图片 (请确保你有一张名为 'test.jpg' 的图片在脚本同目录下)
# 如果没有图片，这步会报错，但上面的版本打印已经说明安装成功了
try:
    img = cv2.imread('test.jpg')
    if img is not None:
        print("成功读取图片！")
        # 可以在这里对图片进行一些操作，例如显示
        # cv2.imshow('Test Image', img)
        # cv2.waitKey(0) # 等待按键
        # cv2.destroyAllWindows() # 关闭所有窗口
    else:
        print("警告: 在当前目录下未找到 'test.jpg' 图片。")
except Exception as e:
    print(f"读取图片时出错: {e}")
print("OpenCV 测试完成！")

在命令行中运行这个脚本：

python test_opencv.py

常见问题与解决方案 (FAQ)

问题 1：`pip` 不是内部或外部命令... (Windows)

原因：Python 的 Scripts 目录没有被添加到系统的环境变量 PATH 中。
解决方法：
1. 打开“开始”菜单，搜索“编辑系统环境变量”。
2. 在弹出的“系统属性”窗口中，点击“环境变量...”按钮。
3. 在“系统变量”（或“用户变量”）列表中，找到名为 Path 的变量，选中它并点击“编辑...”。
4. 在“编辑环境变量”窗口中，点击“新建”，然后添加 Python 的安装路径下的 Scripts 文件夹。C:\Users\你的用户名\AppData\Local\Programs\Python\Python311\Scripts。
5. （同样重要）确保 Path 变量中也包含了 Python 的根目录，C:\Users\你的用户名\AppData\Local\Programs\Python\Python311。
6. 一路点击“确定”保存所有更改，然后重新打开一个新的命令行窗口再试。

问题 2：Permission denied (macOS / Linux)

原因：尝试使用 sudo pip install,这不是一个好习惯。
解决方法：
- 推荐：使用用户级别的安装，无需 sudo。
```
pip install --user opencv-python
```
- 如果仍然遇到权限问题，可能是 pip 本身需要升级，先升级 pip：
```
python -m pip install --upgrade pip
```
  然后再重新安装 OpenCV。

问题 3：安装速度非常慢或失败

原因：默认从 PyPI 的官方服务器下载,国内用户访问较慢。
解决方法：使用国内镜像源,例如使用清华大学的镜像源。
```
# 使用 -i 参数指定镜像源
pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple
```
你也可以将这个镜像源设为默认，在你的用户目录下创建一个名为 pip 的文件夹，并在里面创建一个 pip.ini 文件（Windows）或 pip.conf 文件（macOS/Linux）,内容如下：
```
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
```

问题 4：`ModuleNotFoundError: No module named 'cv2'`

原因：
1. OpenCV 没有安装成功。
2. 你在错误的 Python 环境中运行代码（你安装了 Python 3.10，但 VS Code 或 PyCharm 配置的是 Python 3.9）。
解决方法：
1. 重新检查安装步骤，确保 pip install 命令没有报错。
2. 在命令行中再次运行 python -c "import cv2; print(cv2.__version__)"，如果这行命令能成功，说明 pip 安装是没问题的。
3. 检查你的 IDE（如 VS Code, PyCharm）使用的 Python 解释器路径是否与你在命令行中使用的 python 命令指向同一个解释器，在 IDE 中通常可以切换解释器。

安装 Python：从官网下载，并**务必勾选

python opencv xiezai

核心概念：OpenCV-Python vs. OpenCV Contrib

第一步：安装 Python

第二步：使用 pip 下载并安装 OpenCV

第三步：验证安装