为何poetry安装opencv-python后Jupyter仍无法导入cv2？

错误摘要 #

在Jupyter Notebook中执行以下代码时失败：

import cv2
cv2.__version__

报错信息：

ModuleNotFoundError: No module named 'cv2'.

尝试操作 #

• Poetry安装无效：项目用Poetry管理依赖，执行poetry add opencv-python安装成功，终端执行poetry show opencv-python能显示版本，但Jupyter仍报相同错误。
• pip安装有效：终端执行pip install opencv-python后，错误消失，代码可正常运行。

疑问 #

1. 为何pip可行而Poetry不行？
2. 如何仅用Poetry管理项目，无需使用pip？

环境信息 #

• IDE：VSCode 1.81.1
• 使用DevContainer，镜像为jupyter/datascience-notebook:python-3.11.4，集成Poetry特性
• Jupyter使用Python 3.11.4内核
• 项目根目录有poetry.toml，配置[virtualenvs] create = false
• poetry env info显示系统Python路径为/usr/local/py-utils/venvs/poetry/bin/python3，Jupyter中sys.executable为/opt/conda/bin/python，二者路径不一致

解答 #

1. 为什么pip可行而Poetry不行？ #

核心原因是Poetry与Jupyter使用的Python环境不匹配：

• Poetry当前绑定的是/usr/local/py-utils/venvs/poetry/bin/python3环境，执行poetry add会将包安装到该环境下。
• Jupyter内核使用的是/opt/conda/bin/python对应的Conda环境，若pip是在激活该Conda环境的终端中执行，包会被安装到Jupyter正在使用的环境，因此能被识别。
• 加上你设置了[virtualenvs] create = false，Poetry会直接使用它识别到的系统默认Python，而非创建独立虚拟环境，进一步放大了环境不匹配的问题。

2. 如何仅用Poetry管理项目，无需使用pip？ #

解决核心是让Poetry与Jupyter共用同一个Python环境，具体步骤如下：

步骤1：让Poetry绑定Jupyter的Conda环境

先在终端激活Jupyter对应的Conda环境：

conda activate base  # Jupyter使用的/opt/conda/bin/python通常对应base环境

然后让Poetry绑定该环境的Python解释器：

poetry env use /opt/conda/bin/python

执行后用poetry env info确认路径已变为/opt/conda/bin/python。

步骤2：重新用Poetry安装依赖

清理之前的安装记录，再重新安装opencv-python：

poetry remove opencv-python
poetry add opencv-python

步骤3：验证Jupyter内核

若Jupyter仍无法识别包，需确认内核指向正确环境：

• 在VSCode的Jupyter Notebook中，点击右上角内核选择器，确认选择的是Poetry绑定的Conda环境（Python 3.11.4，路径/opt/conda/bin/python）。
• 若没有对应内核，手动添加：

/opt/conda/bin/python -m ipykernel install --user --name=poetry-conda-env --display-name="Python (Poetry Conda)"

之后在Jupyter中选择该新内核即可。

步骤4：调整Poetry配置（可选）

若希望后续Poetry默认使用该Conda环境，修改项目根目录的poetry.toml：

[virtualenvs]
create = false
python = "/opt/conda/bin/python"

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