如何将含OpenCV、NumPy依赖的Python项目打包为exe文件

直接用PyInstaller打包即可，py2exe停止维护多年，对高版本Python、新版OpenCV兼容性极差；auto-py-to-exe是PyInstaller的图形化包装，新手误选冗余参数反而容易触发打包错误，直接敲命令行操作稳定性最高。

前置准备 #

• 提前确认你运行原代码的Python环境可正常执行脚本，无OpenCV、NumPy的导入报错。在当前环境安装PyInstaller，执行命令：pip install pyinstaller
• 新建一个干净的空文件夹，把你项目的入口py文件（比如命名为project.py）放进去；项目用到的本地素材（图片、模型、配置文件等）统一放到该文件夹下的子目录中，代码里调用素材全部用相对路径，不要写死C盘/D盘的绝对路径。
• 如果你的Anaconda全局环境装了上百个无关库，建议新建一个干净虚拟环境，只安装pyinstaller、opencv-python、numpy三个依赖再打包，能把最终exe体积从几百MB压到几十MB。

打包操作步骤 #

• 打开命令提示符，执行cd 你的项目文件夹路径切换到项目所在目录，比如项目放在D:\cv_project就输入cd D:\cv_project回车。
• 执行适配OpenCV/NumPy的专用打包命令：
  pyinstaller -F -w --collect-data cv2 --hidden-import numpy project.py
  参数说明：
  • -F：将所有依赖打包为单个exe文件，方便课程作业提交
  • -w：运行exe时不弹出黑色命令行窗口，如果你的项目需要命令行交互输入，删掉这个参数
  • --collect-data cv2：自动收集OpenCV自带的dll、级联分类器等资源文件，解决运行时找不到OpenCV相关文件的报错
  • --hidden-import numpy：补全PyInstaller漏抓的NumPy依赖，解决NumPy导入报错
• 等待命令行输出completed successfully提示后，打开项目文件夹下自动生成的dist文件夹，里面的exe文件就是打包好的可执行程序。

常见问题排查 #

• 运行exe提示找不到素材：把你存素材的文件夹，按照代码里的相对路径结构，和exe放在同一级目录即可。
• 还是报NumPy相关错误：执行pip install numpy==1.23.5降级NumPy到兼容性最好的版本，重新执行打包命令即可。
• 杀毒软件误删exe：打包前暂时关闭杀毒软件，或者把生成的exe加入杀毒软件白名单就行。

打包完成后，建议把exe复制到没有安装Python的电脑上完整跑一遍所有功能，确认和本地编辑器运行效果一致，避免课程演示时出问题。

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