VSCode虚拟环境(venv)提示No module named 'cv2' 终端运行正常

• 安装opencv-python相关依赖后，运行代码报错：ModuleNotFoundError: No module named 'cv2'
• 已尝试执行以下安装命令，问题未解决：
  • pip install opencv-python
  • pip install opencv-contrib-python
  • pip install opencv-python opencv-python-headless
  • python3 -m pip install opencv-python
  • pip3 install opencv-python --upgrade
• 已知环境特征：
  • 故障仅在VSCode加载的venv虚拟环境中出现
  • 系统终端直接运行测试代码无报错，可正常返回cv2版本号：

import cv2
print(cv2.__version__)

运行返回值为4.6.0

• 当前使用Python版本为Python 3.9
• 新建空白venv虚拟环境不会触发该问题
• 故障截图：

本质是VSCode绑定的虚拟环境解释器和包安装路径不匹配，旧venv的路径配置缓存异常，导致终端执行的pip命令把包装到了全局环境或者其他虚拟环境里，当前VSCode选中的venv中实际未安装对应包。

按顺序操作即可：

• 校准VSCode选中的Python解释器
  按快捷键Ctrl+Shift+P（Mac系统按Cmd+Shift+P）调出命令面板，搜索Python: Select Interpreter，在弹出的列表里选中当前项目venv目录下的解释器：
  • Windows系统路径为：./项目venv文件夹名/Scripts/python.exe
  • Mac/Linux系统路径为：./项目venv文件夹名/bin/python
    不要选全局Python或者其他conda/venv环境的解释器。
• 强制在当前venv内重装opencv
  打开VSCode内置终端，确认终端行首有(你的venv名称)的激活前缀，执行以下命令：
  python -m pip install opencv-python --force-reinstall --no-cache-dir
  必须用python -m pip的方式调用当前解释器对应的pip，不要直接用pip/pip3命令，避免包装到其他环境。
• 配置异常兜底修复
  如果前两步操作完还是报错，先关闭VSCode：
  • 打开venv目录下的pyvenv.cfg文件，检查home字段的路径是否和本地安装Python3.9的实际路径一致，不一致直接修改保存
  • 进入venv下的Lib/site-packages目录，删除所有名称带opencv、cv2的文件夹
  • 重新打开VSCode激活venv，再次执行第二步的强制安装命令即可。

内容的提问来源于stack exchange，提问作者Piero