使用Beeware打包含cv2的Python程序为exe时遇ModuleNotFoundError

1. 确认OpenCV在pyproject.toml中正确声明 #

Beeware依赖pyproject.toml管理打包依赖，务必将opencv-python（或opencv-contrib-python）添加到dependencies列表：

[tool.poetry.dependencies]
python = "^3.10"
opencv-python = "^4.8.0"
# 其他项目依赖...

如果使用pip而非poetry，要保证requirements.txt里包含OpenCV，且Beeware能正确读取该文件。

2. 配置Beeware打包时包含OpenCV二进制文件 #

OpenCV包含二进制扩展组件，Beeware默认可能未自动打包这些文件。需在pyproject.toml中添加额外配置，指定要包含的cv2文件：

[tool.briefcase.app.your-app-name]
# 其他已有配置...
extra-package-data = {
    "cv2": ["*.pyd", "*.dll", "lib/*.dll"]
}

注意路径要匹配你本地Python环境中cv2的实际文件结构，Windows环境下cv2的二进制文件通常在Lib/site-packages/cv2目录下。

3. 清理缓存后重新打包 #

旧的打包缓存可能残留错误配置，执行以下命令重置后重新构建：

briefcase clean
briefcase build
briefcase package

4. 验证打包后的文件结构 #

打包完成后，找到exe所在目录（通常在dist/<your-app-name>/windows/<version>下），检查app/Python/Lib/site-packages下是否有完整的cv2文件夹，包含所有必要的.pyd和.dll文件。如果缺失，手动从本地Python环境的site-packages/cv2复制对应文件到该目录，再测试exe运行情况。

5. 尝试替换为opencv-python-headless（无GUI需求时） #

如果你的应用仅需图像处理功能，不需要OpenCV的GUI组件（如imshow），可以换成opencv-python-headless，它的依赖更精简，打包兼容性更好：

pip uninstall opencv-python
pip install opencv-python-headless

更新pyproject.toml或requirements.txt后重新打包即可。

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