Python 安装 OpenCV 方法：快速搞定环境配置 – wiki基地

作者： /

Python 安装 OpenCV：快速搞定环境配置（超详细教程）

OpenCV（Open Source Computer Vision Library）是一个开源的计算机视觉和机器学习软件库。它包含了超过 2500 个优化的算法，可用于各种图像和视频处理任务，如人脸检测、对象识别、图像分割、运动跟踪等。对于任何从事计算机视觉、图像处理、深度学习相关工作的开发者来说，OpenCV 都是一个必备的工具。

本文将详细介绍在不同操作系统（Windows、macOS、Linux）上使用 Python 安装 OpenCV 的各种方法，并提供常见问题的解决方案，确保您能够快速、顺利地配置好 OpenCV 环境，开启您的计算机视觉之旅。

一、安装前的准备工作

在开始安装 OpenCV 之前，我们需要确保系统已经具备了以下条件：

  1. Python 环境： OpenCV 支持 Python 2.7 和 Python 3.x 版本。强烈建议使用 Python 3.x，因为 Python 2.7 已经停止维护。您可以通过在终端或命令提示符中输入 python --version 或 python3 --version 来检查已安装的 Python 版本。如果没有安装 Python，请先下载并安装 Python。

  2. 包管理器（pip）： pip 是 Python 的包管理工具，用于安装和管理 Python 包。大多数 Python 安装程序都会默认安装 pip。您可以通过在终端或命令提示符中输入 pip --version 或 pip3 --version 来检查 pip 是否已安装。如果没有安装 pip，请根据您的操作系统进行安装。

  3. 虚拟环境（可选但强烈建议）： 使用虚拟环境可以为每个项目创建独立的 Python 环境，避免不同项目之间的包依赖冲突。强烈建议使用虚拟环境来安装 OpenCV。常用的虚拟环境管理工具有 venv（Python 3.3 及以上版本自带）、virtualenv 等。

    • 使用 venv 创建虚拟环境：

      “`bash

      在项目目录下创建虚拟环境（假设虚拟环境名为 venv）

      python3 -m venv venv

      激活虚拟环境

      Windows

      venv\Scripts\activate

      macOS/Linux

      source venv/bin/activate
      “`

    • 使用 virtualenv 创建虚拟环境：

      “`bash

      安装 virtualenv（如果未安装）

      pip install virtualenv

      在项目目录下创建虚拟环境（假设虚拟环境名为 venv）

      virtualenv venv

      激活虚拟环境

      Windows

      venv\Scripts\activate

      macOS/Linux

      source venv/bin/activate
      “`

  4. 合适的编译器(Windows)：如果你选择编译安装OpenCV，在 Windows 上安装 OpenCV，你可能需要安装合适的C++编译器，例如 Microsoft Visual Studio。

一旦您的系统满足了以上条件，就可以开始安装 OpenCV 了。

二、安装 OpenCV 的方法

安装 OpenCV 主要有两种方法：

  1. 使用 pip 安装预编译的二进制包（简单快捷）： 这是最简单、最快捷的安装方式，适用于大多数用户。pip 会自动下载并安装与您的操作系统和 Python 版本相匹配的 OpenCV 预编译包。

  2. 从源代码编译安装（更灵活，可定制）： 这种方式允许您自定义 OpenCV 的编译选项，例如启用或禁用某些模块、使用特定的优化选项等。但是，从源代码编译安装需要更多的时间和配置，并且可能需要解决一些依赖问题。

2.1 使用 pip 安装预编译的二进制包

这是安装 OpenCV 最简单的方法，只需要一条命令即可完成。

  1. 激活虚拟环境（如果使用了虚拟环境）：

    “`bash

    Windows

    venv\Scripts\activate

    macOS/Linux

    source venv/bin/activate
    “`

  2. 安装 OpenCV：

    OpenCV 在 PyPI 上有两个主要的包：

    • opencv-python：这是主要的 OpenCV 包，包含了核心功能和主要的模块。对于大多数用户来说，安装这个包就足够了。

    • opencv-contrib-python：这个包除了包含 opencv-python 的所有内容外，还包含了额外的贡献模块（contrib modules）。这些贡献模块提供了一些实验性的、非稳定的或者专利受限的算法。如果您需要使用这些额外的模块，可以安装这个包。

    根据您的需求，选择安装其中一个包：

    “`bash

    安装主要包

    pip install opencv-python

    安装包含贡献模块的包

    pip install opencv-contrib-python
    “`
    安装contrib包通常能解决大部分“No module named ‘cv2’”的错误。

  3. 验证安装：

    安装完成后，我们可以通过一个简单的 Python 脚本来验证 OpenCV 是否安装成功：

    “`python
    import cv2

    print(cv2.version)
    “`

    如果输出了 OpenCV 的版本号，则说明安装成功。如果没有输出版本号或提示错误，请参考本文第四部分的“常见问题及解决方案”。

2.2 从源代码编译安装

从源代码编译安装 OpenCV 提供了更大的灵活性，可以根据您的需求进行定制。但是，这种方法需要更多的时间和配置。

以下是在不同操作系统上从源代码编译安装 OpenCV 的步骤：

2.2.1 Windows

  1. 安装依赖项：

    • CMake： CMake 是一个跨平台的构建工具，用于生成构建 OpenCV 所需的项目文件。您可以从 CMake 官网下载并安装 CMake。
    • Visual Studio： Visual Studio 是 Microsoft 的集成开发环境（IDE），包含了 C++ 编译器和其他必要的工具。您可以下载并安装 Visual Studio Community 版本（免费）。确保在安装过程中选择“使用 C++ 的桌面开发”工作负载，并勾选必要的组件（如 MSBuild、C++ 核心功能等）。
    • Python 和 NumPy： 确保已安装 Python 和 NumPy。
    • 可选依赖:
      • Contrib模块: 如果需要编译contrib模块，需要从OpenCV的GitHub仓库和opencv_contrib仓库下载源代码.
      • CUDA: 如果你有NVIDIA显卡并希望使用GPU加速，可以安装CUDA Toolkit和cuDNN。

  2. 下载 OpenCV 源代码：

    您可以从 OpenCV 的 GitHub 仓库下载源代码：

    bash
    git clone https://github.com/opencv/opencv.git
    如果你需要contrib模块，同时下载：
    bash
    git clone https://github.com/opencv/opencv_contrib.git

  3. 配置 CMake：

    • 打开 CMake GUI。
    • 在“Where is the source code”中，选择 OpenCV 源代码目录。
    • 在“Where to build the binaries”中，选择一个空目录用于存放构建生成的文件。
    • 点击“Configure”。
    • 选择您的 Visual Studio 版本作为生成器（Generator）。
    • 如果需要contrib模块，在OPENCV_EXTRA_MODULES_PATH选项中，设置opencv_contrib/modules文件夹的路径。
    • 根据需要修改其他 CMake 选项（例如，启用或禁用某些模块）。
    • 点击“Generate”。

  4. 编译 OpenCV：

    • 打开 Visual Studio。
    • 打开 CMake 生成的项目文件（在构建目录中找到 OpenCV.sln 文件）。
    • 在“解决方案配置”中选择“Release”。
    • 在“解决方案平台”中选择“x64”（如果您的系统是 64 位的）。
    • 右键单击“ALL_BUILD”项目，选择“生成”。
    • 等待编译完成。
    • 右键单击“INSTALL”项目，选择“生成”。这将把 OpenCV 安装到 CMake 中指定的安装目录（默认为 C:\Program Files\OpenCV）。

  5. 配置环境变量：

    • 将 OpenCV 的 bin 目录（例如 C:\Program Files\OpenCV\bin）添加到系统的 PATH 环境变量中。
    • 如果您使用了虚拟环境，可以将OpenCV的build/python_loader文件夹（具体路径根据你的编译设置）下的cv2文件夹拷贝到虚拟环境的Lib/site-packages目录下。

  6. 验证安装：

    “`python
    import cv2

    print(cv2.version)
    “`

2.2.2 macOS

  1. 安装依赖项：

    • Xcode Command Line Tools： 打开终端并运行以下命令：

      bash
      xcode-select --install

    • Homebrew： Homebrew 是 macOS 的包管理器。如果您还没有安装 Homebrew，请按照 Homebrew 官网的说明进行安装。

    • CMake、Python 和 NumPy： 使用 Homebrew 安装：

      bash
      brew install cmake python3 numpy
      * 可选依赖:
      * Contrib模块: 如果需要编译contrib模块，需要从OpenCV的GitHub仓库和opencv_contrib仓库下载源代码.

  2. 下载 OpenCV 源代码：
    与Windows相同,使用git clone下载opencv和opencv_contrib(可选)。

  3. 配置 CMake：

    • 创建一个构建目录：

      bash
      cd opencv
      mkdir build
      cd build

    • 运行 CMake：

      bash
      cmake -D CMAKE_BUILD_TYPE=Release \
      -D CMAKE_INSTALL_PREFIX=/usr/local \
      -D PYTHON3_EXECUTABLE=$(which python3) \
      -D PYTHON_INCLUDE_DIR=$(python3 -c "from distutils.sysconfig import get_python_inc; print(get_python_inc())") \
      -D PYTHON_LIBRARY=$(python3 -c "import distutils.sysconfig as sysconfig; print(sysconfig.get_config_var('LIBDIR'))") \
      -D OPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules \
      ..
      注意：
      * CMAKE_INSTALL_PREFIX 指定了安装路径。
      * PYTHON3_EXECUTABLE、PYTHON_INCLUDE_DIR 和 PYTHON_LIBRARY 指定了 Python 解释器、头文件和库的路径。
      * OPENCV_EXTRA_MODULES_PATH用于指定contrib模块的位置（可选）。
      * 根据您的实际情况调整这些路径。

  4. 编译 OpenCV：

    bash
    make -j$(nproc) # 使用所有可用的 CPU 核心进行编译
    sudo make install

  5. 验证安装：
    同上。

2.2.3 Linux

  1. 安装依赖项：

    • 使用您的 Linux 发行版的包管理器安装必要的依赖项。例如，在 Ubuntu 或 Debian 上，可以使用以下命令：

      bash
      sudo apt-get update
      sudo apt-get install -y cmake g++ wget unzip \
      libjpeg-dev libpng-dev libtiff-dev \
      libavcodec-dev libavformat-dev libswscale-dev \
      libgtk2.0-dev libcanberra-gtk* \
      libxvidcore-dev libx264-dev \
      python3-dev python3-numpy \
      libtbb2 libtbb-dev libdc1394-22-dev \
      libv4l-dev v4l-utils \
      libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
      libavresample-dev libvorbis-dev libxine2-dev \
      libfaac-dev libmp3lame-dev libtheora-dev \
      libopencore-amrnb-dev libopencore-amrwb-dev \
      libopenblas-dev libatlas-base-dev libblas-dev \
      liblapack-dev libeigen3-dev gfortran \
      libhdf5-dev protobuf-compiler

      在 Fedora 或 CentOS 上，可以使用 yum 或 dnf 命令安装类似的依赖项。请根据您的发行版进行调整。
      * 可选依赖:
      * Contrib模块: 如果需要编译contrib模块，需要从OpenCV的GitHub仓库和opencv_contrib仓库下载源代码.

  2. 下载 OpenCV 源代码：
    与Windows相同,使用git clone下载opencv和opencv_contrib(可选)。

  3. 配置 CMake：

    • 创建一个构建目录：

      bash
      cd opencv
      mkdir build
      cd build

    • 运行 CMake：

      “`bash
      cmake -D CMAKE_BUILD_TYPE=Release \
      -D CMAKE_INSTALL_PREFIX=/usr/local \
      -D WITH_TBB=ON \
      -D WITH_V4L=ON \
      -D WITH_OPENGL=ON \
      -D WITH_GSTREAMER=ON \
      -D OPENCV_GENERATE_PKGCONFIG=ON \
      -D OPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules \
      -D BUILD_opencv_python3=ON\
      -D PYTHON3_EXECUTABLE=$(which python3) \
      -D PYTHON_INCLUDE_DIR=$(python3 -c “from distutils.sysconfig import get_python_inc; print(get_python_inc())”) \
      -D PYTHON_LIBRARY=$(python3 -c “import distutils.sysconfig as sysconfig; print(sysconfig.get_config_var(‘LIBDIR’))”) \
      ..

      ``
      注意：
      *      CMAKE_INSTALL_PREFIX指定了安装路径。
      *      WITH_TBB、WITH_V4L、WITH_OPENGL和WITH_GSTREAMER启用了相应的可选依赖项。
      *      OPENCV_GENERATE_PKGCONFIG=ON生成一个.pc文件，方便其他程序链接 OpenCV。
      *      OPENCV_EXTRA_MODULES_PATH`用于指定contrib模块的位置（可选）。
      * 根据实际情况调整选项.

  4. 编译 OpenCV：

    bash
    make -j$(nproc) # 使用所有可用的 CPU 核心进行编译
    sudo make install

  5. 配置环境变量 (可选)：

    • 如果您将 OpenCV 安装到了非标准路径，可能需要将 OpenCV 的库目录添加到 LD_LIBRARY_PATH 环境变量中：

      bash
      export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

      将此行添加到您的 .bashrc 或 .bash_profile 文件中，以便在每次打开终端时自动设置环境变量。

    • 如果生成了.pc文件，你可能需要设置PKG_CONFIG_PATH环境变量。

  6. 验证安装
    同上。

三、不同Python环境下的安装

3.1 Anaconda

Anaconda 是一个流行的 Python 数据科学平台，自带了一个包管理器 conda。如果您使用 Anaconda，可以使用 conda 来安装 OpenCV：

  1. 激活 Anaconda 环境（如果使用了虚拟环境）：

    bash
    conda activate <your_environment_name>

  2. 安装 OpenCV：

    bash
    conda install -c conda-forge opencv
    -c conda-forge 指定从 conda-forge 频道安装 OpenCV。conda-forge 提供了最新版本的 OpenCV 和其他许多软件包。

  3. 验证安装：
    同上。

3.2 Jupyter Notebook/Lab

Jupyter Notebook 和 JupyterLab 是常用的交互式 Python 环境。在 Jupyter Notebook 或 JupyterLab 中安装 OpenCV，您可以直接在单元格中运行安装命令：

python
!pip install opencv-python # 或者 !pip install opencv-contrib-python

或者,如果你使用conda:

python
!conda install -c conda-forge opencv -y
!符号表示在单元格中执行 shell 命令。

四、常见问题及解决方案

在安装 OpenCV 的过程中，可能会遇到一些问题。以下是一些常见问题及其解决方案：

  1. No module named 'cv2' 错误：

    • 原因：

      • 未安装 OpenCV。
      • 安装了错误的 OpenCV 包（例如，只安装了 opencv-python-headless，而没有安装 opencv-python）。
      • Python 解释器找不到 OpenCV 模块。
      • 虚拟环境未激活或 OpenCV 未安装在虚拟环境中。
      • 多个 Python 版本冲突。
      • 安装了多个 OpenCV 版本，导致冲突。
      • (源代码编译)环境变量未正确设置。

    • 解决方案：

      • 确保已安装 opencv-python 或 opencv-contrib-python。
      • 如果使用了虚拟环境，请确保已激活虚拟环境，并且 OpenCV 已安装在该虚拟环境中。
      • 检查 Python 解释器的路径是否正确，确保它能够找到 OpenCV 模块。
      • 尝试重新安装 OpenCV。
      • 如果安装了多个 Python 版本，请确保您使用的 Python 版本与安装 OpenCV 的版本一致。
      • 卸载所有 OpenCV 版本，然后重新安装所需的版本。
      • (源代码编译)确保将OpenCV的bin目录(Windows)或lib目录添加到PATH或LD_LIBRARY_PATH环境变量。

  2. ImportError: DLL load failed 错误（Windows）：

    • 原因：

      • 缺少必要的 DLL 文件。
      • DLL 文件版本不兼容。
      • 环境变量未正确设置。

    • 解决方案：

      • 确保已安装所有必要的依赖项（例如，Microsoft Visual C++ Redistributable）。
      • 尝试重新安装 OpenCV。
      • 检查环境变量 PATH 是否包含了 OpenCV 的 bin 目录。
      • 如果安装了多个版本的 OpenCV 或 Python，请确保它们之间没有冲突。

  3. 编译错误:

    • 原因:
      • 缺少依赖项。
      • CMake配置错误。
      • 编译器版本过旧。
    • 解决方案:
    • 仔细阅读错误信息，通常会指出缺少的依赖。
    • 仔细检查CMake配置，确保所有选项都正确设置。
    • 更新编译器到最新版本。

  4. pip install 超时错误：

    • 原因：

      • 网络连接不稳定。
      • PyPI 服务器响应慢。

    • 解决方案：

      • 检查您的网络连接。

      • 尝试更换 pip 的镜像源。例如，使用清华大学的镜像源：

        bash
        pip install -i https://pypi.tuna.tsinghua.edu.cn/simple opencv-python
        * 增加 pip 的超时时间：

        bash
        pip --default-timeout=100 install opencv-python

  5. conda install 速度慢或失败：

    • 原因：

      • 网络连接不稳定。
      • conda 服务器响应慢。

    • 解决方案：

      • 检查您的网络连接。

      • 尝试更换 conda 的镜像源。例如，使用清华大学的镜像源：

        bash
        conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
        conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
        conda config --set show_channel_urls yes

      • 使用 mamba 代替 conda。mamba 是一个更快的 conda 替代品：

        bash
        conda install -n base -c conda-forge mamba
        mamba install opencv

五、总结

本文详细介绍了在不同操作系统上使用 Python 安装 OpenCV 的各种方法，包括使用 pip 安装预编译的二进制包和从源代码编译安装。我们还介绍了在 Anaconda 和 Jupyter Notebook/Lab 环境中安装 OpenCV 的方法，并提供了一些常见问题的解决方案。

无论您是初学者还是有经验的开发者，希望本文都能帮助您快速、顺利地配置好 OpenCV 环境，开启您的计算机视觉之旅。如果您在安装过程中遇到任何问题，请仔细阅读错误信息，并参考本文提供的解决方案。如果问题仍然无法解决，请在相关的论坛或社区寻求帮助。

现在，您已经准备好开始使用 OpenCV 进行各种图像和视频处理任务了！祝您在计算机视觉的世界里探索愉快！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部