Python OpenCV 安装教程（Windows/Linux/macOS） – wiki基地

作者： /

Python OpenCV 安装教程 (Windows/Linux/macOS)

OpenCV (Open Source Computer Vision Library) 是一个开源的计算机视觉和机器学习软件库。它包含了大量的算法，涵盖了计算机视觉领域的主要方面，例如图像处理、特征检测、物体识别、机器学习等。Python 作为最受欢迎的编程语言之一，与 OpenCV 结合使用可以快速高效地进行计算机视觉开发。

本教程将详细介绍如何在 Windows、Linux 和 macOS 系统上安装 Python OpenCV。

前提条件

在开始安装之前，请确保您的系统满足以下条件：

  1. Python 环境：确保您的系统已安装 Python 3.x 版本。推荐使用 Python 3.6 或更高版本。您可以通过在终端或命令提示符中运行 python --version 或 python3 --version 来检查。
  2. pip 包管理器：pip 是 Python 的包安装程序。它通常随 Python 一起安装。如果您的 Python 环境中没有 pip，可以参考官方文档进行安装。

  3. 虚拟环境 (推荐)：为了避免包之间的冲突并保持项目依赖的整洁，强烈建议为每个项目使用 Python 虚拟环境。

    • 创建虚拟环境：
      bash
      python -m venv myenv
    • 激活虚拟环境：
      • Windows:
        bash
        .\myenv\Scripts\activate
      • Linux/macOS:
        bash
        source myenv/bin/activate
    • 退出虚拟环境：
      bash
      deactivate

Windows 系统安装

在 Windows 上安装 OpenCV-Python 相对简单，主要通过 pip 进行。

  1. 激活虚拟环境 (如果使用)
    打开命令提示符 (CMD) 或 PowerShell，并激活您的虚拟环境：
    bash
    .\myenv\Scripts\activate

  2. 安装 OpenCV
    使用 pip 安装 opencv-python。这个包包含了预编译的 OpenCV 库以及 Python 绑定。
    bash
    pip install opencv-python
    如果您还需要额外的模块 (如 SIFT/SURF 等非免费模块)，可以安装 opencv-contrib-python：
    bash
    pip install opencv-contrib-python
    注意：opencv-python 和 opencv-contrib-python 包含了大部分常见功能。通常情况下，您只需安装其中一个。opencv-contrib-python 包含更多的功能，但文件体积更大。

  3. 验证安装
    打开 Python 解释器或创建一个 Python 脚本文件 (例如 test_cv.py)：
    python
    import cv2
    print(cv2.__version__)
    如果能够成功打印 OpenCV 的版本号，则说明安装成功。

Linux 系统安装

在 Linux 上安装 OpenCV-Python 有两种主要方法：通过 pip 安装预编译包 (推荐) 或从源代码编译安装。对于大多数用户，使用 pip 是最简单快捷的方式。

方法一：通过 pip 安装 (推荐)

  1. 更新系统包
    在安装任何新软件之前，最好先更新您的系统包列表：
    bash
    sudo apt update
    sudo apt upgrade
    (对于基于 Debian/Ubuntu 的系统，其他发行版请使用相应的包管理器命令，例如 yum update for CentOS/RHEL)

  2. 安装 Python 及其开发工具
    确保您有 Python 3 和 pip。同时，安装必要的 Python 开发头文件，这在某些情况下可能需要：
    bash
    sudo apt install python3 python3-pip python3-venv python3-dev

  3. 激活虚拟环境 (如果使用)
    bash
    source myenv/bin/activate

  4. 安装 OpenCV
    同样，使用 pip 安装 opencv-python 或 opencv-contrib-python：
    bash
    pip install opencv-python
    # 或者
    pip install opencv-contrib-python

  5. 验证安装
    python
    import cv2
    print(cv2.__version__)

方法二：从源代码编译安装 (适用于需要特定配置或最新功能的用户)

从源代码编译 OpenCV 允许您自定义构建选项、包含特定模块或优化性能。这通常更复杂，需要安装大量的开发依赖。

  1. 安装必要的构建工具和依赖
    bash
    sudo apt install build-essential cmake git pkg-config
    sudo apt install libgtk2.0-dev libcanberra-gtk-module libcanberra-gtk3-module # GUI 支持
    sudo apt install libjpeg-dev libpng-dev libtiff-dev # 图像格式支持
    sudo apt install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev # 视频 I/O 支持
    sudo apt install libxvidcore-dev libx264-dev # 视频编解码器
    sudo apt install libatlas-base-dev gfortran # 优化数学库
    sudo apt install python3-dev # Python 3 开发头文件
    可能还需要安装 numpy：
    bash
    pip install numpy

  2. 下载 OpenCV 源代码
    从 GitHub 克隆 OpenCV 和 OpenCV Contrib 仓库：
    bash
    git clone https://github.com/opencv/opencv.git
    git clone https://github.com/opencv/opencv_contrib.git
    或者下载特定版本的发布包。

  3. 创建构建目录并配置 CMake
    进入 opencv 目录，创建 build 文件夹，并进入该文件夹：
    bash
    cd opencv
    mkdir build
    cd build
    运行 cmake 配置：
    bash
    cmake -D CMAKE_BUILD_TYPE=RELEASE \
    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D INSTALL_PYTHON_EXAMPLES=ON \
    -D INSTALL_C_EXAMPLES=OFF \
    -D OPENCV_ENABLE_NONFREE=ON \
    -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
    -D PYTHON_EXECUTABLE=/usr/bin/python3 \
    -D BUILD_EXAMPLES=ON ..
    解释:

    • -D CMAKE_BUILD_TYPE=RELEASE: 构建发布版本。
    • -D CMAKE_INSTALL_PREFIX=/usr/local: 安装路径。
    • -D INSTALL_PYTHON_EXAMPLES=ON: 安装 Python 示例。
    • -D OPENCV_ENABLE_NONFREE=ON: 启用非免费模块 (如 SIFT/SURF)，需要 opencv_contrib。
    • -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules: 指定 opencv_contrib 模块路径。根据你下载的路径调整。
    • -D PYTHON_EXECUTABLE=/usr/bin/python3: 指定 Python 解释器路径。如果你在虚拟环境中安装，可能需要指向虚拟环境的 Python 解释器。

  4. 编译和安装
    bash
    make -j$(nproc) # 使用所有 CPU 核心进行编译，加快速度
    sudo make install
    sudo ldconfig # 更新共享库缓存

  5. 验证安装
    python
    import cv2
    print(cv2.__version__)
    如果 Python 找不到 cv2 模块，你可能需要手动将 OpenCV 的 Python 绑定添加到 PYTHONPATH 环境变量中。通常，Python 绑定文件 (例如 cv2.cpython-3x-x86_64-linux-gnu.so) 会被安装到 /usr/local/lib/python3.x/dist-packages 或类似路径下。

macOS 系统安装

在 macOS 上安装 OpenCV-Python 也主要通过 pip，但使用 Homebrew 包管理器来安装一些依赖会更方便。

  1. 安装 Homebrew (如果未安装)
    Homebrew 是 macOS 上一个优秀的包管理器。如果尚未安装，请在终端运行：
    bash
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. 安装 Python 3 (如果未安装)
    虽然 macOS 自带 Python，但通常是旧版本。推荐通过 Homebrew 安装最新版本：
    bash
    brew install python
    这会将 Python 3 安装在 /usr/local/bin/python3。

  3. 安装必要的依赖 (通过 Homebrew)
    为了确保 OpenCV 能够正常工作，尤其是如果将来从源代码编译，建议安装一些基本依赖：
    bash
    brew install cmake pkg-config jpeg libpng tiff openexr

  4. 激活虚拟环境 (如果使用)
    bash
    source myenv/bin/activate

  5. 安装 OpenCV
    通过 pip 安装预编译的 opencv-python 或 opencv-contrib-python：
    bash
    pip install opencv-python
    # 或者
    pip install opencv-contrib-python

  6. 验证安装
    python
    import cv2
    print(cv2.__version__)

常见问题与故障排除

  • ModuleNotFoundError: No module named 'cv2'：

    • 确保您已激活正确的虚拟环境。
    • 检查是否已成功安装 opencv-python 或 opencv-contrib-python (pip list)。
    • 如果是从源代码编译安装，确认 cv2.so (或 .pyd) 文件位于 Python 解释器能找到的路径中，例如在 site-packages 目录下。

  • pip 安装失败：

    • 检查您的网络连接。
    • 尝试更新 pip (python -m pip install --upgrade pip).
    • 尝试指定镜像源，例如使用清华大学镜像站：
      bash
      pip install opencv-python -i https://pypi.tuna.tsinghua.edu.cn/simple

  • 无法加载图像或视频：

    • 确保图像/视频文件路径正确。
    • 检查文件权限。
    • 如果从源代码编译，请确保在 cmake 配置时启用了 libjpeg-dev, libpng-dev, libtiff-dev, libavcodec-dev 等相关依赖。

  • 版本冲突：

    • 使用虚拟环境是解决版本冲突的最佳实践。
    • 如果出现其他库与 OpenCV 冲突，可以尝试在新虚拟环境中重新安装所有依赖。

通过遵循上述步骤，您应该能够在 Windows、Linux 和 macOS 系统上成功安装 Python OpenCV，并开始您的计算机视觉项目。

滚动至顶部