新手必看！VSCode&PyCharm 配置 OpenCV 超详细教程（支持 Python 和 C++ 双语言）

适用对象 ：初学者，希望在 VSCode 与 PyCharm 两款常用 IDE 中，学会配置并使用 OpenCV，分别实现 Python 与 C++ 环境的快速上手。

适用平台 ：Windows 10/11（本文以 Windows 为主要示范，Linux 或 macOS 用户可参照各自系统的包管理细节进行适当调整）。

摘要

本文为新手用户提供了最全的 VSCode & PyCharm 配置 OpenCV 教程，涵盖 Python 与 C++ 双语言环境搭建与调试流程。文章详细介绍了在 Windows 系统下安装 Python、Visual Studio Build Tools、CMake、OpenCV 预编译包，并手把手演示如何在 VSCode 中创建虚拟环境、安装 opencv-python、配置 CMakeLists.txt、生成并运行 C++ 示例程序。快速实现图像读取、灰度转换、窗口显示等基础操作，为后续计算机视觉开发打下坚实基础。

picture.image

新手必看！VSCode&PyCharm 配置 OpenCV 超详细教程（支持 Python 和 C++ 双语言）

环境准备

1.1 系统要求

操作系统 ：Windows 10/11（建议 64 位）。
磁盘空间 ：至少 10 GB 可用空间，用于安装 IDE、编译工具与 OpenCV 库。
内存：至少 8 GB，编译 C++ 源码时尽量保证运行流畅。
网络：可正常访问外网，用于下载 Python 包、OpenCV 预编译包等。

提示：如果你使用的是 Linux 或 macOS，Python 部分几乎一致；C++ 部分请改用相应系统的包管理（比如 Linux 下用 apt 或 yum 安装 libopencv-dev，macOS 下用 Homebrew brew install opencv），VSCode 与 PyCharm 的配置思路相同，但路径与命令略有不同，请自行替换。

1.2 工具下载与安装概览

| 工具/软件 | 作用 | 官方下载地址 | | --- | --- | --- | | Python | 提供 Python 运行时，执行 OpenCV Python 示例 | https://www.python.org/downloads/ | | Visual Studio Build Tools | 提供 Windows 下 C++ 编译器（MSVC）、CMake 等构建工具 | https://visualstudio.microsoft.com/zh-hans/downloads/ (选择“Build Tools for Visual Studio 2022”) | | VSCode | 微软出品的轻量级跨平台 IDE，适合 Python & C++ 开发 | https://code.visualstudio.com/ | | PyCharm | JetBrains 出品的 Python IDE | https://www.jetbrains.com/pycharm/ | | OpenCV 预编译包 | 提供 C++ 版库文件（Windows 下为 .exe 或 .zip ） | https://opencv.org/releases/ |

安装顺序建议 ：

安装 Python，把“Add Python 3.x to PATH”勾选上（方便后续在终端直接使用 python 命令）。

安装 Visual Studio Build Tools，并在安装过程中勾选 “C++ build tools” 与 “Windows 10/11 SDK”。

安装 VSCode 与 PyCharm。

下载并解压 OpenCV 预编译包。

按照下面章节的步骤，分别配置 Python 与 C++ 环境。

Python + VSCode 环境配置

本节将带你从零开始，在 Windows 平台上搭建基于 VSCode 的 Python + OpenCV 开发环境，并运行一个简单图像读取与显示示例。

2.1 安装 Python

下载 Python 安装包

访问 Python 官网，点击最新 3.x 版本（例如 Python 3.11.x ）的 Windows Installer（根据自己系统选择 64-bit）。

运行安装程序

勾选页面底部的 “Add Python 3.x to PATH” ，然后点击 “Install Now” 。
等待安装完成。

验证安装

打开 命令提示符 (CMD) 或 PowerShell ，输入：

  
python --version

若显示类似 Python 3.11.x，说明安装成功。

同时也可以验证 pip：

  
pip --version

若显示 pip 23.x.x from ...，表示 pip 可用。

2.2 创建并激活虚拟环境

为了保证项目依赖独立，建议使用虚拟环境（venv）。

打开 命令提示符 (CMD) 或 PowerShell ，进入你希望存放项目的文件夹，例如：

  
cd C:\Users\你的用户名\Projects  
mkdir OpenCV\_VSCode\_Python  
cd OpenCV\_VSCode\_Python

创建虚拟环境：

  
python -m venv venv

这会在当前文件夹下创建一个名为 venv 的子文件夹，里面包括独立的 Python 解释器。 3. 激活虚拟环境：

在 命令提示符 ：

  
venv\Scripts\activate.bat

在 PowerShell （可能需要先解除脚本执行限制）：

  
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser  
.\venv\Scripts\Activate.ps1

激活后，终端提示符会出现前缀 (venv)。

注意：后续所有在终端执行的 pip install、python 命令，都将在该虚拟环境中生效。如需退出虚拟环境，输入 deactivate 即可。

2.3 安装 VSCode 及 Python 插件

下载 VSCode

访问 VSCode 官网，点击下载适用于 Windows 的安装程序。
安装时勾选 “Add to PATH”、“Register Code as Editor for supported file types” 等选项（方便后续直接在资源管理器右键打开）。

打开 VSCode

安装完成后，双击运行 VSCode。

安装 Python 插件

在左侧扩展图标（Extensions）中，搜索 “Python”，由 Microsoft 发布的官方扩展为：

  
Python (ms-python.python)

点击 “Install” 进行安装。
安装完毕后，VSCode 底部状态栏会出现已识别的 Python 解释器选项。

2.4 安装 OpenCV（Python 版）

确保虚拟环境已激活

如果之前已经退出，重新打开项目目录，在终端中重新激活：

  
cd C:\Users\你的用户名\Projects\OpenCV\_VSCode\_Python  
venv\Scripts\activate.bat

安装 OpenCV-Python 包

opencv-python ：主模块，包含核心功能。
opencv-contrib-python ：包含额外的算法模块（contrib），推荐同时安装。
在终端输入：

  
pip install opencv-python opencv-contrib-python

解释：

验证安装

在终端启动 Python 交互：

  
python

在交互式命令行输入：

  
import cv2  
print(cv2.\_\_version\_\_)

如果输出类似 4.8.0 或者其他版本号，就说明安装成功。
输入 exit() 退出 Python 交互。

2.5 在 VSCode 中创建、配置项目

打开项目文件夹

在 VSCode 中，依次点击：文件 → 打开文件夹...，选择刚才创建的 C:\Users\你的用户名\Projects\OpenCV\_VSCode\_Python 文件夹。

选择 Python 解释器

点击右下角“Python 版本号”，在弹出的“Python 选择解释器”列表里，选择以 venv 路径开头的那个项（例如 C:\...\OpenCV\_VSCode\_Python\venv\Scripts\python.exe ）。
在 VSCode 窗口的右下角，会显示当前默认的 Python 解释器。如果它还不是 venv 中的解释器：

创建示例脚本文件

在项目根目录下，点击左侧资源管理器里的“新建文件”，命名为 opencv\_test.py 。

自动补全 / IntelliSense 检查

打开 opencv\_test.py，输入：

  
import cv2  
  
# 测试 OpenCV 是否可用  
img = cv2.imread('test.jpg')  
cv2.imshow('Test Window', img)  
cv2.waitKey(0)  
cv2.destroyAllWindows()

如果 import 时没有红线报错，说明 VSCode 已经正确识别 cv2 模块。

注意：示例中使用 cv2.imshow 需要在 Windows 本地环境执行，且要确保当前目录下存在名为 test.jpg 的图像文件。可以自行下载一张测试图片命名为 test.jpg 放在项目根目录。

2.6 编写并运行 Python 示例脚本

准备测试图像

在项目根目录下，新建一个名为 test.jpg 的图像（任意一张照片即可）。

完整示例代码 （opencv\_test.py）：

  
import cv2  
  
def main():  
    # 读取本目录下的 test.jpg  
    img = cv2.imread('test.jpg')  
    if img isNone:  
        print('无法读取 test.jpg，请确认文件存在于当前目录')  
        return  
  
    # 将图像转换为灰度并显示  
    gray = cv2.cvtColor(img, cv2.COLOR\_BGR2GRAY)  
  
    cv2.imshow('原图', img)  
    cv2.imshow('灰度图', gray)  
  
    print('按任意键关闭窗口...')  
    cv2.waitKey(0)  
    cv2.destroyAllWindows()  
  
if \_\_name\_\_ == '\_\_main\_\_':  
    main()

在 VSCode 中执行

打开 opencv\_test.py，可以点击右上方的绿色运行按钮（▶），或者在终端中手动输入：

  
python opencv\_test.py

如果成功，会分别弹出两个窗口：一个显示彩色原图，一个显示灰度图。终端会打印 按任意键关闭窗口...。按任意键后，窗口关闭，程序结束。

至此，Python + VSCode + OpenCV 环境配置完成！

C++ + VSCode 环境配置

本节将介绍如何在 Windows 平台下，通过 VSCode + CMake + MSVC 构建并使用 OpenCV C++ 库，详细说明下载预编译包、设置环境变量、配置 VSCode 对 C++ 的编译与调试等步骤。

3.1 安装 C++ 编译工具（Windows：Visual Studio Build Tools）

下载

访问 Visual Studio 官网下载页，向下滚动到 “Tools for Visual Studio 2022” 部分，找到 “Build Tools for Visual Studio 2022” 并点击下载。

安装

MSVC v143 或 v142 – VS 2022 C++ x64/x86 构建工具
Windows 10 或 11 SDK
CMake 工具
运行下载得到的 vs\_BuildTools.exe 安装程序。
选择工作负载（Workloads）：勾选 “使用 C++ 的桌面开发”（Desktop development with C++） ，确保下方包含：
点击右下角 “Install”；等待下载并安装，安装过程大约需要 5 GB 空间与数分钟时间。

验证

安装完成后，打开 x64 Native Tools Command Prompt for VS 2022 （在「开始菜单 → Visual Studio 2022」中即可找到）。
输入：

cl

如果出现 Microsoft (R) C/C++ Optimizing Compiler 等输出，则说明 MSVC 已就绪。

同时验证 CMake：

  
cmake --version

如果输出类似 cmake version 3.27.x，说明 CMake 安装成功。

3.2 下载并配置 OpenCV 预编译包

下载 OpenCV Windows 预编译包

访问 OpenCV Releases（或在浏览器搜索 “OpenCV releases”），找到最新的 Windows 预编译版本，例如 OpenCV 4.8.0 。
下载 .exe 安装包（例如 opencv-4.8.0-vc14\_vc15.exe ）或者 .zip 包。

解压/安装

如果下载的是 .exe 安装包，双击运行，选择安装目录（例如 C:\opencv\opencv-4.8.0 ）。
如果下载的是 .zip ，右键解压到例如 C:\opencv\opencv-4.8.0 。

环境变量配置

添加 OPENCV_DIR
修改 Path
验证（在新的命令提示符中）

  
echo %OPENCV\_DIR%

若输出上述路径，则生效。

在 “系统变量(S)” 区域，找到 Path，选中后点击 “编辑(I)...”。
添加一行：

  
C:\opencv\opencv-4.8.0\build\x64\vc15\bin

点击确定，保存退出。
右键“此电脑” → “属性” → “高级系统设置” → “环境变量(N)...”。
在 “系统变量(S)” 区域，点击 “新建(W)...”，变量名填 OPENCV\_DIR，变量值填：

  
C:\opencv\opencv-4.8.0\build\x64\vc15   # 根据实际版本和文件夹填写，通常到 build\x64\vc15

点击确定。

说明：

vc15 对应 VS 2017/2019/2022 通用的构建；若你安装的 OpenCV 版本是基于 VS 2019/2022，则文件夹可能是 vc14 / vc15 。请根据实际目录填写。

build\x64\vc15\bin 下包含了各类 .dll 动态库，以及 opencv\_world480.dll （单一 DLL）或多个 opencv\_*.dll 。

3.3 安装 VSCode C/C++ 扩展

打开 VSCode

如果还未运行 VSCode，请双击打开。

安装 C/C++ 扩展

在左侧扩展市场 (Extensions) 中，搜索：

  
C/C++

由 Microsoft 发布的官方扩展“C/C++” (ms-vscode.cpptools) 位于搜索结果第一。
点击 “Install” 进行安装。

安装 CMake Tools 扩展（可选，但强烈推荐）

在扩展市场搜索：

  
CMake Tools

由 Microsoft 发布的 “CMake Tools” (ms-vscode.cmake-tools) 拓展可以让 VSCode 本身识别 CMake 项目、自动生成配置，便于日后管理复杂项目。
点击 “Install” 安装。

小贴士 ：

安装完毕后，VSCode 右下角会出现 “CMake: [未激活/Kit: None]” 的字样，表示已加载 CMake Tools。

CMake Tools 能自动检测系统中的 CMake、编译器（如 MSVC），并允许你通过 GUI 直接选择 “配置”、“生成”、“编译”等操作。

3.4 在 VSCode 中创建 C++ 项目（CMake + 示例代码）

下面以 CMake 构建示例讲解如何集成 OpenCV。

新建项目文件夹

在你喜欢的位置（例如 C:\Users\你的用户名\Projects\OpenCV\_VSCode\_CPP）创建文件夹：

  
mkdir C:\Users\你的用户名\Projects\OpenCV\_VSCode\_CPP  
cd C:\Users\你的用户名\Projects\OpenCV\_VSCode\_CPP

准备项目结构

CMakeLists.txt ：CMake 构建配置文件。
src/main.cpp ：C++ 示例代码文件。
image/test.jpg ：测试用图像。可自行准备一张照片并放置其中。
在 OpenCV\_VSCode\_CPP 目录下，新建以下文件/文件夹结构：

  
OpenCV\_VSCode\_CPP  
├── CMakeLists.txt  
├── src  
│   └── main.cpp  
└── image  
    └── test.jpg

其中：

编写 CMakeLists.txt 在项目根目录（OpenCV\_VSCode\_CPP）新建 CMakeLists.txt，内容示例如下（请根据你的 OpenCV 版本与文件夹路径自行替换 OPENCV\_DIR）：

  
cmake\_minimum\_required(VERSION 3.10)  
project(OpenCV\_VSCode\_CPP)  
  
# 设置 C++ 标准（此处为 C++17，可自定义）  
set(CMAKE\_CXX\_STANDARD 17)  
set(CMAKE\_CXX\_STANDARD\_REQUIRED ON)  
  
# 查找 OpenCV 包  
# OPENCV\_DIR 环境变量已在系统中定义，指向 C:/opencv/opencv-4.8.0/build/x64/vc15  
find\_package(OpenCV REQUIRED)  
  
# 输出包含目录（可选，便于在编译输出中查看）  
message(STATUS "OpenCV include dirs: ${OpenCV\_INCLUDE\_DIRS}")  
message(STATUS "OpenCV libraries: ${OpenCV\_LIBS}")  
  
# 添加可执行文件  
add\_executable(${PROJECT\_NAME} src/main.cpp)  
  
# 链接 OpenCV 库  
target\_link\_libraries(${PROJECT\_NAME} PRIVATE ${OpenCV\_LIBS})

说明：

find\_package(OpenCV REQUIRED) ：依赖于环境变量 OPENCV\_DIR ，CMake 会在 {OPENCV\_DIR}/x64/vc15/lib/cmake/opencv4 下寻找相关配置。
${OpenCV\_INCLUDE\_DIRS} 包含了 include 文件夹的路径，比如 C:/opencv/opencv-4.8.0/build/include 。
${OpenCV\_LIBS} 包含了所有需要链接的 .lib 文件（静态链接或动态链接均由 CMake 自动选择）。

编写 main.cpp 示例 在 src/main.cpp 中，复制以下代码：

  
#include <opencv2/opencv.hpp>  
#include <iostream>  
  
int main() {  
    // 构造图像路径（相对路径：工程目录/image/test.jpg）  
    std::string image\_path = "../image/test.jpg";  
    cv::Mat img = cv::imread(image\_path);  
    if (img.empty()) {  
        std::cerr << "无法打开图像: " << image\_path << std::endl;  
        return-1;  
    }  
  
    cv::Mat gray;  
    cv::cvtColor(img, gray, cv::COLOR\_BGR2GRAY);  
  
    cv::imshow("原图 (Color)", img);  
    cv::imshow("灰度图 (Gray)", gray);  
  
    std::cout << "按任意键退出..." << std::endl;  
    cv::waitKey(0);  
  
    cv::destroyAllWindows();  
    return0;  
}

放置测试图片

在 OpenCV\_VSCode\_CPP/image 文件夹下放置一张 test.jpg。
路径示例：

  
C:\Users\你的用户名\Projects\OpenCV\_VSCode\_CPP\image\test.jpg

3.5 配置 `c\_cpp\_properties.json`、`tasks.json` 与 `launch.json`

如果你安装了 CMake Tools 扩展，可以让 VSCode 自动生成大部分配置；这里展示手动配置方式，以便理解其原理。若使用 CMake Tools，后续手动配置步骤可略做简化。

3.5.1 c_cpp_properties.json

此文件用来告知 VSCode C/C++ 扩展，头文件搜索路径（includePath）和 IntelliSense 选项。位置：.vscode/c\_cpp\_properties.json。

在项目根目录下新建 .vscode 文件夹，再在其中新建 c\_cpp\_properties.json，内容示例：

  
{  
    "configurations": [  
        {  
            "name": "Win32",  
            "includePath": [  
                "${workspaceFolder}/**",  
                "C:/opencv/opencv-4.8.0/build/include"  
            ],  
            "defines": [  
                "\_DEBUG",  
                "UNICODE",  
                "\_UNICODE"  
            ],  
            "windowsSdkVersion": "10.0.19041.0",  
            "compilerPath": "C:/Program Files/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.35.32215/bin/Hostx64/x64/cl.exe",  
            "cStandard": "c11",  
            "cppStandard": "c++17",  
            "intelliSenseMode": "windows-msvc-x64"  
        }  
    ],  
    "version": 4  
}

请根据实际安装路径更改 ：

includePath 中第二行要与 C:\opencv\opencv-4.8.0\build\include 路径一致。

compilerPath 为 MSVC 编译器的绝对路径，可在命令提示符中 where cl.exe 查到，然后复制完整路径。

windowsSdkVersion 根据你安装的 Windows SDK 版本填写，若不知道可以先留空或使用默认，IntelliSense 会自动识别。

3.5.2 tasks.json

此文件告诉 VSCode 如何调用编译命令，把 CMake 的生成任务或直接 cl/g++ 编译语句写入这里，以便按下“Ctrl+Shift+B”时直接编译。位置：.vscode/tasks.json。

示例：使用 CMake 编译

  
{  
    "version": "2.0.0",  
    "tasks": [  
        {  
            "label": "CMake: Configure",  
            "type": "shell",  
            "command": "cmake",  
            "args": [  
                "-S",  
                "${workspaceFolder}",  
                "-B",  
                "${workspaceFolder}/build",  
                "-G",  
                "NMake Makefiles"  
            ],  
            "group": {  
                "kind": "build",  
                "isDefault": true  
            },  
            "problemMatcher": []  
        },  
        {  
            "label": "CMake: Build",  
            "type": "shell",  
            "command": "cmake",  
            "args": [  
                "--build",  
                "${workspaceFolder}/build",  
                "--config",  
                "Debug"  
            ],  
            "group": "build",  
            "problemMatcher": []  
        }  
    ]  
}

说明：

-S ${workspaceFolder} ：指明 CMakeLists.txt 所在目录。

-B ${workspaceFolder}/build ：生成输出目录为 build 文件夹。

-G "NMake Makefiles" ：使用 NMake 工具链（MSVC）；如果你更喜欢使用 Visual Studio 生成文件，可写 -G "Visual Studio 17 2022" ，但此时 VSCode 下的命令行编译方式会不同。

“CMake: Configure” 与 “CMake: Build” 两个任务，可以分别按顺序运行，也可绑定到快捷键。

如果你不想使用 CMake，而想手动调用 cl.exe 进行编译，也可写成：

  
{  
    "version": "2.0.0",  
    "tasks": [  
        {  
            "label": "Compile main.cpp",  
            "type": "shell",  
            "command": "\"C:/Program Files/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.35.32215/bin/Hostx64/x64/cl.exe\"",  
            "args": [  
                "/EHsc",  
                "/I", "C:/opencv/opencv-4.8.0/build/include",  
                "src\\main.cpp",  
                "/link",  
                "/LIBPATH:C:/opencv/opencv-4.8.0/build/x64/vc15/lib",  
                "opencv\_world480.lib"  
            ],  
            "group": {  
                "kind": "build",  
                "isDefault": true  
            },  
            "presentation": {  
                "reveal": "always"  
            },  
            "problemMatcher": "$msCompile"  
        }  
    ]  
}

说明：

指定了 cl.exe 的路径。

/I 参数加入了 OpenCV 的头文件目录。

/link 后面通过 /LIBPATH 指定了 .lib 库所在目录。

最后直接链接了 opencv\_world480.lib （如果你的版本号不同，请替换为相应的 .lib 名称）。

上述任务执行后，会在项目根目录生成 main.exe 可执行文件。

3.5.3 launch.json

此文件用于 VSCode 的调试配置（Debugging），当你按下 F5 或点击调试时，VSCode 会按照这里的配置启动程序。位置：.vscode/launch.json。

示例（调试 CMake 生成的可执行文件）

  
{  
    "version": "0.2.0",  
    "configurations": [  
        {  
            "name": "Debug: OpenCV\_Cpp (CMake)",  
            "type": "cppvsdbg",  
            "request": "launch",  
            "program": "${workspaceFolder}/build/Debug/OpenCV\_VSCode\_CPP.exe",  
            "args": [],  
            "stopAtEntry": false,  
            "cwd": "${workspaceFolder}",  
            "environment": [],  
            "console": "externalTerminal",  
            "preLaunchTask": "CMake: Build"  
        }  
    ]  
}

说明：

program ：可执行文件的路径，请根据你在 CMake 中选择的生成模式（Debug/Release）和项目名进行修改。

preLaunchTask ：在调试前自动执行哪个 Task，此处我们指向了 “CMake: Build”，即每次调试前会自动触发编译。

"console": "externalTerminal" ：程序调试时使用外部终端弹出窗口，便于使用 cv::imshow 弹窗显示图像。

如果你采用手动 cl 编译方式，则 program 路径改为 ${workspaceFolder}/main.exe，并将 preLaunchTask 改为你在 tasks.json 中定义的 “Compile main.cpp”。

3.6 编译并运行 C++ 示例程序

打开 VSCode，选择配置

点击右下角的 “Configure CMake Project” 或者 “选择任务/运行任务”，若你按照上文使用了 CMake Tools 扩展，可直接在 VSCode 右下方的状态栏找到 “CMake: [Kit: ...]” 并选择你需要的 Kit（如 “Desktop x64”）；然后点击 “Configure” 让 CMake 生成工程。
如果不使用 CMake Tools 扩展，则可以直接按 Ctrl+Shift+B ，选择 “CMake: Configure” → “CMake: Build”。

生成与编译

按 Ctrl+Shift+B ，选择 “Compile main.cpp” 任务。
等待终端中出现 “main.cpp: ...” 编译信息，并最终生成 main.exe 。
点击 VSCode 底部状态栏 “CMake: [Debug]” → 选择 “Build”。
等待输出窗口中出现 “-- Build finished” 提示。
使用 CMake Tools ：
手动 cl 方式 ：

调试或运行

若要调试，按 F5 或点击左侧活动栏 “Run and Debug” → 选择 “Debug: OpenCV_Cpp (CMake)”。
若仅要运行，直接在 命令提示符 、PowerShell 或 VSCode 终端输入：

  
cd build\Debug  
.\OpenCV\_VSCode\_CPP.exe

或者：

  
cd C:\Users\你的用户名\Projects\OpenCV\_VSCode\_CPP  
main.exe   # 如果你使用手动 cl 编译

程序运行后，会弹出两个窗口：一个显示彩色图像 test.jpg，一个显示灰度图像，终端会打印 按任意键退出...。

注意事项 ：

如果运行时提示找不到 opencv\_world480.dll（或其他版本号），请确认：

已正确将 C:\opencv\opencv-4.8.0\build\x64\vc15\bin 添加到系统 Path 。

重新打开 VSCode 或命令提示符，确保环境变量生效。

如果仍报错，可将 opencv\_world480.dll 手动复制到可执行文件所在目录（build\Debug 或项目根目录）进行临时调试。

Python + PyCharm 环境配置

本节演示如何在 PyCharm 中搭建 Python + OpenCV 环境，流程与 VSCode 类似，但由 PyCharm 自带的 GUI 操作来完成虚拟环境创建与包管理。

4.1 安装 PyCharm

下载

访问 PyCharm 官网，下载社区版（Community）即可，若有教育/工作需要商用高级功能，可选择 Professional 版。

安装

双击下载得到的 pycharm-community-2025.x.exe ，一路下一步即可。
建议安装时勾选 “Create Desktop Entry” 以及 “Update PATH variable”，方便后续从命令行启动。

首次启动

运行 PyCharm，选择 “Skip Remaining and Set Defaults” 跳过主题、插件等预设，也可以按需自定义。

4.2 创建 Python 项目并选择解释器

启动 PyCharm

在欢迎界面中点击 “New Project” 。

配置项目

PyCharm 默认会使用系统默认 Python，也会让你创建一个新的虚拟环境。
选择 “New environment using Virtualenv”，如果你想让 PyCharm 自动创建并管理虚拟环境。
或者，你也可以选择 “Existing interpreter”，并指向之前手动创建的 venv：

  
C:\Users\你的用户名\Projects\OpenCV\_PyCharm\_Python\venv\Scripts\python.exe

Location ：选择一个项目路径，例如 C:\Users\你的用户名\Projects\OpenCV\_PyCharm\_Python。
Python Interpreter （关键）：
点击 “Create”。

项目结构

PyCharm 创建后，会在项目根目录下生成：

  
OpenCV\_PyCharm\_Python  
├── .idea  
└── main.py  # 默认文件，可重命名或删除

4.3 在 PyCharm 中安装 OpenCV（Python 版）

打开 Settings（设置）

依次点击菜单栏：File → Settings...（Windows）或 PyCharm → Preferences...（macOS）。

Project Interpreter 管理

在设置框中，左侧选择 Project: OpenCV_PyCharm_Python → Python Interpreter 。
如果已经有正确的虚拟环境或系统 Python 被选中，在右侧会列出当前已安装的包列表（可能为空）。
点击右侧列表上方的 “+” 按钮，打开 “Available Packages” 搜索框。

搜索并安装 opencv-python

在搜索框中输入 opencv-python ，选中后点击 “Install Package” 按钮。
等待安装成功，期间会自动处理依赖。

验证安装

安装完成后，点击 “OK” 或 “Apply” 关闭设置。
在项目的 src 目录（若无可新建一个 src 文件夹），右键新建 Python 文件 opencv\_test.py，输入：

  
import cv2  
  
print("OpenCV 版本：", cv2.\_\_version\_\_)  
  
# 测试读取并显示  
img = cv2.imread('test.jpg')  
if img is None:  
    print("无法读取 test.jpg，请确认文件存在于项目根目录或指定路径")  
else:  
    cv2.imshow("Show", img)  
    cv2.waitKey(0)  
    cv2.destroyAllWindows()

在项目根目录放置一张 test.jpg，然后右键 opencv\_test.py → “Run 'opencv_test'”。
运行后，若终端输出 OpenCV 版本号并弹窗显示图片，说明 Python + OpenCV 在 PyCharm 中配置成功。

4.4 编写并运行 Python 示例脚本

项目结构

建议将示例脚本都放在 src 或 scripts 文件夹下，并把测试图像放到项目根目录，结构示例：

  
OpenCV\_PyCharm\_Python  
├── .idea  
├── src  
│   └── opencv\_test.py  
└── test.jpg

示例代码详解 （src/opencv\_test.py）

  
import cv2  
import sys  
  
def main():  
    # 读取本项目根目录下的 test.jpg  
    img = cv2.imread('test.jpg')  
    if img isNone:  
        print('Error: 无法读取 test.jpg')  
        sys.exit(1)  
  
    # 获取图像尺寸（高度、宽度、通道数）  
    height, width, channels = img.shape  
    print(f'图像尺寸：{width}x{height}，通道数：{channels}')  
  
    # 转换为灰度图  
    gray = cv2.cvtColor(img, cv2.COLOR\_BGR2GRAY)  
  
    # 画一个矩形框，示范如何使用绘制函数  
    top\_left = (int(width * 0.2), int(height * 0.2))  
    bottom\_right = (int(width * 0.8), int(height * 0.8))  
    cv2.rectangle(img, top\_left, bottom\_right, (0, 255, 0), 2)  
  
    # 显示原图与灰度图  
    cv2.imshow("原图 + 矩形框", img)  
    cv2.imshow("灰度图", gray)  
  
    print("按任意键关闭窗口...")  
    cv2.waitKey(0)  
    cv2.destroyAllWindows()  
  
if \_\_name\_\_ == "\_\_main\_\_":  
    main()

运行方式：在 PyCharm 左侧项目文件树，右键 opencv\_test.py → Run 'opencv_test'；
观察控制台打印尺寸信息，窗口会弹出原图与灰度图。

至此，Python + PyCharm + OpenCV 环境配置完成！

C++ + PyCharm 环境配置

PyCharm 对 C/C++ 的支持与 VSCode/CLion 之间有所差异。PyCharm Community 版本本身并不包含原生 C++ 项目模板或强力的 CMake GUI 集成。如果你使用 Professional 版本，也只能得到有限的 CMake 支持。所以，本节将演示一种“在 PyCharm 中使用 CMake + 外部工具 / 终端”来编写、编译、运行 C++ + OpenCV 的方法。

5.1 PyCharm 对 C++ 支持说明

PyCharm Community vs Professional

Community 版 ：只针对 Python 开发，有基本的文本编辑功能。可以用作编写 C++ 代码的文本编辑器，但没有内置 CMake 项目模板或调试器。
Professional 版 ：具备一定的 CMake 支持（如识别 CMakeLists.txt 并提供语法高亮），但是并不如 CLion 那般完善。

推荐方案

对于初学者 ，若重点还是想在一个 IDE 中同时管理 Python 和 C++，可使用 PyCharm Professional，并利用其对 CMake 的基础识别。
如果你只有 Community 版 ，依然可以在项目中编写 C++ 源码和 CMakeLists.txt，但必须依靠 PyCharm 终端或外部构建工具来完成编译与调试。

插件

PyCharm 有第三方插件（如 C/C++ ），但大多数需要专业版才能生效。此处暂不使用插件，而采用最通用的方式：在 PyCharm 中打开 CMake 项目，配合终端完成编译、运行、调试。

5.2 利用 CMake 构建 C++ 项目并使用终端/外部工具

假设你已经安装了 Visual Studio Build Tools、CMake、并且系统环境变量中包含了 OpenCV 的路径（参见第 3 章 的内容）。下面以一个名为 OpenCV\_PyCharm\_CPP 的项目演示如何在 PyCharm 中操作。

创建项目

打开 PyCharm（Professional 推荐），点击 “Open” ，选择你在 VSCode 项目中已经创建好的 C:\Users\你的用户名\Projects\OpenCV\_VSCode\_CPP 文件夹（或者新建一个独立同样结构的项目）。
PyCharm 会自动识别到一个 CMakeLists.txt 文件，并在右上角显示 “ Load CMake Project ” 或 “CMake: [未配置]”。

配置 CMake Profiles（仅 Professional 可见）

CMake executable ：系统中可执行的 cmake 路径（通常在环境变量中已经可用，写 cmake 即可）。
Generator ：选择 NMake Makefiles （与 VSCode 配置保持一致）。
CMake Options ：如果需要传入 -DCMAKE\_BUILD\_TYPE=Debug ，可以在此处添加。
点击右上角的 CMake 符号，进入 “CMake Profiles” 设置。
新建一个 Profile，命名为 Debug，并指定：
保存后，PyCharm 会自动使用该 Profile 运行 CMake，生成构建文件。（这一过程可能需要几秒钟）

查看生成结果

CMake 生成的项目文件会位于项目根目录下或 cmake-build-debug（由 PyCharm 默认创建的构建目录）。你会在该目录下看到 .ninja、.ninja\_deps、.ninja\_log 或者 Makefile、CMakeCache.txt 等文件。
如果成功，说明 CMake 已检测了你的 OpenCV 环境。你可以在 “Event Log” 中看到类似：

  
-- OpenCV include dirs: C:/opencv/opencv-4.8.0/build/include  
-- OpenCV libraries: opencv\_world480

编译项目

PyCharm Community 版无法直接调用 CMake 构建。此时，你需要在 PyCharm 内置 Terminal（终端）中手动执行 CMake 命令：

  
cd C:\Users\你的用户名\Projects\OpenCV\_VSCode\_CPP  
mkdir build  
cd build  
cmake -G "NMake Makefiles" -DCMAKE\_BUILD\_TYPE=Debug ..  
nmake

上述命令会在 build\ 下生成 OpenCV\_VSCode\_CPP.exe。
在右上角可以看到一个绿色小锤子图标（Build）。点击它，即可执行 CMake 构建。
或者在菜单 Build → Build Project 。
Professional 版 ：
Community 版 ：

运行与调试

由于 Community 版不支持 C++ 调试器，你可以在 Terminal 中手动执行：

  
cd C:\Users\你的用户名\Projects\OpenCV\_VSCode\_CPP\build  
OpenCV\_VSCode\_CPP.exe

若要调试，只能在使用 Visual Studio Developer Command Prompt 下调用 Debug 版本，或使用其他外部调试器（如 WinDbg），这里不做详细介绍。

在 CMake 构建完成后，PyCharm 会自动发现可执行文件（ .exe ）并在 “Run” 配置中列出。
点击项目右上方的运行配置下拉框，选择 OpenCV\_VSCode\_CPP.exe ，然后点击绿色 ▶，即可运行。
若要调试，点击 “Debug” 小虫子图标，PyCharm 会以 Debug 模式启动。
Professional 版 ：
Community 版 ：

示例验证

运行后，你应当会如同在 VSCode 中一样，看到弹出的图像窗口：彩色原图与灰度图，并在控制台输出 “按任意键退出...”。
确认无错误，即表示 C++ + OpenCV 已在 PyCharm 环境下调通（以 Professional 版为例）。

5.3 在 PyCharm 中运行与调试 C++ 示例

| PyCharm 版本 | 操作方式 | | --- | --- | | Professional |

点击右上角 Run/Debug 配置，选择 OpenCV\_VSCode\_CPP.exe
点击 ▶ 执行，或点击 🐞 进行调试。 | | Community |
在左侧项目窗口，右键点击项目根目录 → “Open in Terminal”。
在终端输入：

cd build

OpenCV\_VSCode\_CPP.exe

若需调试，仅能外部工具） |

小贴士 ：

如果你 Community 版想借助 GUI 形式编译与调试 C++，请使用 CLion 或 VSCode。PyCharm Community 更适合作为文本编辑器与 Python IDE。

PyCharm Professional 可将 CMake 构建过程无缝纳入 IDE，但若需调试核心断点，确保 launch.json / Debug 配置正确指向生成的可执行文件。

常见问题与解决方案

报错 “import cv2: No module named cv2”

原因：Python 环境中没有安装 OpenCV-Python，或 VSCode/PyCharm 中选择的解释器并非预期的虚拟环境。
解决：

确认当前终端是否激活虚拟环境 ( (venv) 前缀)。
在激活后执行 pip install opencv-python 。
在 VSCode 中，点击右下角 Python 版本号，确保选择的解释器路径指向虚拟环境。
在 PyCharm Settings→Project Interpreter 中确认已安装 opencv-python 。

C++ 编译报错 “cannot open source file ‘opencv2/opencv.hpp’”

原因：includePath 中没有正确包含 OpenCV include 目录，或者 find\_package(OpenCV) 失败。
解决：

检查系统环境变量 OPENCV\_DIR 是否正确指向 ...\opencv\build\x64\vc15 。
在 CMakeLists.txt 中打印 ${OpenCV\_INCLUDE\_DIRS} ，确认 CMake 找到的路径正确。
如果手动 cl 编译，在 tasks.json 或命令行也要加上 /I "C:/opencv/opencv-4.8.0/build/include" 。

运行时报错找不到 opencv\_worldXXX.dll

原因：系统 PATH 中没有包含 OpenCV 的 bin 目录，或者尚未重启终端/IDE。
解决：

确认系统环境变量 Path 中已加入 C:\opencv\opencv-4.8.0\build\x64\vc15\bin 。
重启 VSCode、PyCharm 或者操作系统，然后重新运行。
如果问题依旧，可手动复制 opencv\_world480.dll 到可执行文件算法目录（仅作临时测试）。

PyCharm CMake 加载失败 / 无法检测编译器

原因：PyCharm Professional 未正确识别系统中的 CMake 或 MSVC。
解决：

在命令行中执行 cmake --version 、 cl ，确认这两个命令可用。
在 PyCharm Settings → Build, Execution, Deployment → CMake 中，手动指定 CMake 可执行文件完整路径。
在 “CMake Profiles” 中，检查 “Generator” 是否与实际安装的工具链匹配（例如 MSVC 对应 “Visual Studio 17 2022” 或 “NMake Makefiles”）。

VSCode Python 调试无法弹窗显示 cv2.imshow

原因：部分远程/WSL 环境不支持 GUI 弹窗，或者 Python 解释器选择不正确。
解决：

确认使用的是本地 Windows 环境，而非 WSL/Remote SSH。
检查 Python 解释器是否为正确的虚拟环境。
在 VSCode 的 launch.json 中， console 字段改为 "externalTerminal" , 确保弹窗可见。

编译速度很慢 / 内存消耗大

原因：CMake 默认会同时生成 Debug/Release 多种版本，或者没有用到增量编译。
解决：

在 CMakeLists.txt 中指定：

  
set(CMAKE\_BUILD\_TYPE Release)

如果使用 VSCode CMake Tools，切换到单一构建配置（右下角切换 “Debug” 或 “Release”）。
确保不要在同一个目录里反复 rm -rf build/* 再完整重建，而是只在必要时清理。

附录

7.1 Windows 环境变量简要说明

系统变量 vs 用户变量 ：

“系统变量”对所有用户生效；“用户变量”仅对当前 Windows 登录用户生效。
建议将 OPENCV\_DIR 、 Path 中添加 OpenCV 路径放入 系统变量 ，以保证 VSCode/其他工具都能识别。

常用变量 ：

| 变量名 | 建议值 | 作用 | | --- | --- | --- | | OPENCV_DIR | C:\opencv\opencv-4.8.0\build\x64\vc15 | 给 CMake find\_package(OpenCV) 提供路径 | | Path | C:\opencv\opencv-4.8.0\build\x64\vc15\bin | 让系统能找到 opencv\_world480.dll 及其他 .dll | | CMAKE_PREFIX_PATH | （可选） C:\opencv\opencv-4.8.0\build | 让某些 CMake 工具链搜索 OpenCV 时更快捷 |

7.2 CMakeLists.txt 详细示例

如果你想更深入地了解 CMakeLists.txt，下面给出一个更“健壮”的示例，支持 Debug/Release 双配置，并自动设置安装路径：

  
cmake\_minimum\_required(VERSION 3.10)  
project(OpenCV\_VSCode\_CPP)  
  
# 设置 C++ 标准  
set(CMAKE\_CXX\_STANDARD 17)  
set(CMAKE\_CXX\_STANDARD\_REQUIRED ON)  
  
# 防止 Reconfig 时覆盖旧的 Release/Debug 结果  
if (NOT CMAKE\_BUILD\_TYPE)  
  set(CMAKE\_BUILD\_TYPE Release CACHE STRING "Choose the type of build." FORCE)  
endif()  
  
# 查找 OpenCV  
find\_package(OpenCV REQUIRED)  
  
# 打印信息  
message(STATUS "==== OpenCV 信息 ====")  
message(STATUS "OpenCV 版本： ${OpenCV\_VERSION}")  
message(STATUS "OpenCV 包路径： ${OpenCV\_DIR}")  
message(STATUS "OpenCV 头文件目录： ${OpenCV\_INCLUDE\_DIRS}")  
message(STATUS "OpenCV 库文件： ${OpenCV\_LIBS}")  
message(STATUS "====================")  
  
# 指定可执行文件输出目录  
set(EXECUTABLE\_OUTPUT\_PATH ${PROJECT\_BINARY\_DIR}/bin)  
  
# 指定库文件输出目录  
set(LIBRARY\_OUTPUT\_PATH ${PROJECT\_BINARY\_DIR}/lib)  
  
# 包含子目录（如果你有其他子模块可以分开管理）  
# add\_subdirectory(src)  
  
# 添加主程序  
add\_executable(${PROJECT\_NAME} src/main.cpp)  
  
# 链接 OpenCV  
target\_link\_libraries(${PROJECT\_NAME} PRIVATE ${OpenCV\_LIBS})  
  
# 若需安装  
install(TARGETS ${PROJECT\_NAME} RUNTIME DESTINATION bin)

解释：

CMAKE\_BUILD\_TYPE 通过缓存变量管理了 Debug/Release，可在 CMake GUI 或命令行中指定 -DCMAKE\_BUILD\_TYPE=Debug ，否则默认 Release。

将可执行文件输出到 build/bin ，使项目结构更清晰。

install(...) 方便以后打包安装。

7.3 快速回顾

Python + VSCode

安装 Python 并创建虚拟环境；
安装 VSCode Python 扩展；
pip install opencv-python opencv-contrib-python ；
编写 opencv\_test.py ，执行并验证 cv2.imshow 弹窗。

C++ + VSCode

安装 Visual Studio Build Tools（MSVC）+ CMake；
下载并解压 OpenCV Windows 预编译包，配置环境变量 OPENCV\_DIR 与 Path ；
安装 VSCode C/C++、CMake Tools 扩展；
创建含 CMakeLists.txt 和 src/main.cpp 的项目；
在 VSCode 中执行 “CMake: Configure” → “CMake: Build”；
调试（F5）或运行可执行文件，观察图像输出。

Python + PyCharm

安装 PyCharm，新建项目并选择虚拟环境；
在 Project Interpreter 中安装 opencv-python ；
编写并运行 opencv\_test.py ，检查图像显示。

C++ + PyCharm

PyCharm Professional：直接加载 CMake 项目，点击 Build & Run；
PyCharm Community：在内置终端中手动执行 CMake + nmake；
使用外部终端或调试器查看运行结果。

至此，你已经掌握了在 VSCode 与 PyCharm 两大 IDE 下，如何同时配置并运行 OpenCV 的 Python 与 C++ 环境。祝你学习顺利，愉快地开始你的计算机视觉之旅！

picture.image

新手必看！VSCode&PyCharm 配置 OpenCV 超详细教程（支持 Python 和 C++ 双语言）

摘要

环境准备

1.1 系统要求

1.2 工具下载与安装概览

Python + VSCode 环境配置

2.1 安装 Python

2.2 创建并激活虚拟环境

2.3 安装 VSCode 及 Python 插件

2.4 安装 OpenCV（Python 版）

2.5 在 VSCode 中创建、配置项目

2.6 编写并运行 Python 示例脚本

C++ + VSCode 环境配置

3.1 安装 C++ 编译工具（Windows：Visual Studio Build Tools）

3.2 下载并配置 OpenCV 预编译包

3.3 安装 VSCode C/C++ 扩展

3.4 在 VSCode 中创建 C++ 项目（CMake + 示例代码）

3.5 配置 c\_cpp\_properties.json、tasks.json 与 launch.json

3.5.1 c_cpp_properties.json

3.5.2 tasks.json

3.5.3 launch.json

3.6 编译并运行 C++ 示例程序

Python + PyCharm 环境配置

4.1 安装 PyCharm

4.2 创建 Python 项目并选择解释器

4.3 在 PyCharm 中安装 OpenCV（Python 版）

4.4 编写并运行 Python 示例脚本

C++ + PyCharm 环境配置

5.1 PyCharm 对 C++ 支持说明

5.2 利用 CMake 构建 C++ 项目并使用终端/外部工具

5.3 在 PyCharm 中运行与调试 C++ 示例

常见问题与解决方案

附录

7.1 Windows 环境变量简要说明

7.2 CMakeLists.txt 详细示例

7.3 快速回顾

3.5 配置 `c\_cpp\_properties.json`、`tasks.json` 与 `launch.json`