简介将PPOCRLabel半自动标注工具编译封装为exe程序的资源包面向需要进行OCR数据标注的开发者、算法工程师及项目团队免去安装配置PaddlePaddle环境和各种依赖的繁琐步骤解压后双击即可进入图形化标注界面适合文档扫描、车牌识别、证件信息提取等场景。压缩包共2000个文件以py源码、pyd编译扩展、exe主程序、whl依赖包为主另含部分配置文件、模型参数与示例图片整体大小约355MB目录涵盖运行库与依赖便于用户了解工具构成。工具支持在图像上绘制文字框并录入标注内容可执行撤销、重做、保存等操作并能够导出JSON格式的标注数据与PaddleOCR等主流训练流程兼容同时借助PaddlePaddle生态具备部分自动标注能力能明显提高标注效率。目前该资源已有6445人浏览学习适合从零开始接触OCR训练数据准备的用户也适合追求高效标注的进阶开发者。1. 项目概况与打包思路1.1 为什么要打包PPOCRLabel先说背景。PPOCRLabel是PaddleOCR生态里非常实用的半自动标注工具核心价值是把OCR识别结果直接落到标注框里人工只需要修正错字和漏框能省下大量从零框选的时间。但问题也很现实这个工具跑起来依赖Python环境和PaddlePaddle框架我在实际交付时不止一次遇到以下情况标注团队的同事电脑上没装Python装环境又怕把系统搞乱项目验收方要求提供独立的可视化工具而不是一堆源码加命令行换一台机器就要重新配一遍CUDA、PaddlePaddle、Qt相关依赖时间成本太高所以在一次标注任务中我决定把PPOCRLabel打包成Windows下的exe程序做到双击即用。这篇文章就把完整过程、坑点和最终方案记录下来。1.2 打包方案选型对比在动手之前我把主流方案过了一遍这里直接给出横向对比方便你按自己情况选方案优势劣势适不适合PPOCRLabelPyInstaller文档全、社区案例多、支持hook机制打包体积大、偶尔误报毒首选cx_Freeze相对轻量对PyQt5和PaddlePaddle等动态库处理不如PyInstaller省心备选Nuitka编译为C性能好、不易反编译配置成本高PaddlePaddle这类大型库编译时容易出幺蛾子不推荐Docker封装环境隔离彻底不适合Windows桌面端直接交付不适合本场景综合权衡我选了PyInstaller 单目录模式。为什么不选单文件模式PPOCRLabel依赖PaddleOCR模型文件、Qt相关插件和大量动态库单文件模式每次启动都要解压到临时目录启动速度明显变慢而且在部分企业电脑上更容易被杀毒软件拦截。单目录模式虽然看起来文件多但胜在稳定可控。2. 环境准备与依赖处理2.1 干净环境的重要性强烈建议在干净的Python虚拟环境中进行打包不要直接使用系统Python。原因很直接系统Python里装了太多无关包PyInstaller打包时会尝试把它们一起收集进去导致包体膨胀甚至因为某些包互相冲突导致启动报错。我用的环境如下Windows 10 专业版 22H2Python 3.9.1332位和64位都试过最终用64位毕竟PaddlePaddle对64位支持更好PaddlePaddle 2.5.2CPU版PaddleOCR 2.7.0PPOCRLabel 2.1.3创建虚拟环境的命令很简单python -m venv ppocrlabel_env ppocrlabel_env\Scripts\activate这里有个细节要注意安装PaddlePaddle时不要默认装GPU版除非你确认目标机器都有NVIDIA显卡且CUDA环境完整。否则打包出来在别人电脑上跑不起来反而麻烦。纯CPU版本虽然推理慢一些但标注场景下人工修正占大头速度完全够用。2.2 依赖安装顺序有讲究依赖安装顺序会直接影响最终exe能否正常运行这绝对是我踩出来的经验。建议按以下顺序来pip install paddlepaddle2.5.2 pip install paddleocr2.7.0 pip install PPOCRLabel2.1.3为什么要按这个顺序因为PPOCRLabel安装时会自动检测PaddleOCR和PaddlePaddle的版本如果先装PPOCRLabel它可能拉取到某些不兼容的版本组合。装完以后执行一下PPOCRLabel --lang ch如果程序能正常启动说明环境基本OK再继续打包流程。这一步很有必要别急着打包先确认源码能跑打包后的排查范围才会小。2.3 补装PyInstaller和必要的辅助工具pip install pyinstaller5.13.2 pip install pyinstaller-hooks-contribpyinstaller-hooks-contrib一定要装里面包含了PaddlePaddle、PyQt5等常用库的打包hook没有它很多动态库不会自动收集。装完以后最好检查一下hooks是否真的包含paddle相关条目python -c from PyInstaller.utils.hooks import get_hook_config; print(hooks ok)这个检测不复杂但能提前发现hook缺失问题省得后面打包出来运行报错再回头查。3. 基于spec文件的精细化打包流程3.1 编写PPOCRLabel专属spec文件PyInstaller不推荐直接写一长串命令行参数更好的做法是编写spec文件它能把所有打包配置固化下来后面要调整只需要改spec文件重新执行一次构建非常方便。我最终使用的spec文件核心内容如下# -*- mode: python ; coding: utf-8 -*- from PyInstaller.utils.hooks import collect_data_files, collect_submodules datas [] binaries [] hiddenimports [] # 收集PaddleOCR和PPOCRLabel相关数据文件 datas collect_data_files(paddleocr) datas collect_data_files(PPOCRLabel) datas collect_data_files(paddle) # 收集动态链接库尤其是paddle相关 binaries collect_dynamic_libs(paddle) binaries collect_dynamic_libs(paddleocr) # 隐藏导入 hiddenimports collect_submodules(paddleocr) hiddenimports collect_submodules(PPOCRLabel) hiddenimports collect_submodules(paddle) a Analysis( [PPOCRLabel.py], pathex[], binariesbinaries, datasdatas, hiddenimportshiddenimports, hookspath[], hooksconfig{}, runtime_hooks[], excludes[matplotlib, PIL.ImageQt], noarchiveFalse, ) pyz PYZ(a.pure) exe EXE( pyz, a.scripts, exclude_binariesTrue, namePPOCRLabel, debugFalse, bootloader_ignore_signalsFalse, stripFalse, upxTrue, consoleTrue, iconapp.ico, ) coll COLLECT( exe, a.binaries, a.datas, stripFalse, upxTrue, namePPOCRLabel, )注意几个细节upxTrue默认开启但如果安装的UPX版本不兼容某些库反而会损坏二进制文件建议实测后再决定是否开UPXconsoleTrue保留命令行窗口我在开发阶段保留它正式交付时改成consoleFalse避免弹出黑框影响体验iconapp.ico编译前的图标文件需要256x256以上的ico格式直接改后缀名没用3.2 执行打包并查看日志pyinstaller PPOCRLabel.spec --clean --noconfirm打包过程大概需要5到15分钟取决于机器性能。日志出现以下内容说明关键库都被收集到了INFO: Processing pre-safe-import-module hook paddleocr INFO: Processing module hooks... INFO: Loading module hook hook-paddle.py... INFO: Loading module hook hook-paddleocr.py...打包完成后dist目录下会生成PPOCRLabel文件夹里面包含exe主程序和大量依赖文件。但仅仅解压出来能放到别人电脑上用还差得远接下来才是最关键的验证和补缺阶段。3.3 首次启动验证与常见启动崩溃修复双击exe大概率会遇到问题。我首次打包后的经历比较典型启动直接报错ModuleNotFoundError: No module named paddleocr.utils这个错误出现的主要原因是PyInstaller在某些情况下没有完整收集paddleocr的内部子模块。解决办法有两个思路第一个思路是在spec文件的hiddenimports里强制指定hiddenimports [ paddleocr.utils, paddleocr.tools, paddleocr.parser, ppocrlabel.utils, ]第二个思路是在程序入口处加上显式导入。这个方法百试百灵因为显式import过的模块PyInstaller在静态分析阶段就会收入依赖import paddleocr.utils import paddleocr.tools import paddleocr.parser import ppocrlabel.utils两个方法可以一起做因为实在不想打包完才发现漏了某个子模块又要重新打包浪费时间。除了ModuleNotFoundError还有两类非常常见的启动崩溃DLL load failed while importing paddle大概率是VC运行库缺失需要在目标机器上安装VC Redistributableqt.qpa.plugin: Could not find the Qt platform plugin windows这是Qt平台插件没被正确收集需要在spec里加platform plugin路径针对Qt插件问题在spec里显式指定from PyInstaller.utils.hooks import collect_data_files qt_plugins collect_data_files(PyQt5, includes[Qt/plugins/platforms/*, Qt/plugins/imageformats/*]) datas qt_plugins重新打包后再启动程序能正常进入主界面但深坑还在后面模型文件路径问题。4. 模型文件路径与运行环境适配4.1 PaddleOCR模型位置的三种方案PPOCRLabel启动时PaddleOCR会自动下载检测模型和识别模型到用户目录的.paddleocr文件夹。但在打包后的exe环境中程序的工作目录、临时目录和用户目录都跟源码模式不同所以模型文件经常找不到要么就是每次启动都在尝试重新下载。处理这个问题的方案有三种我按推荐程度排序方案一预下载模型并随包分发在源码模式下先手动运行一次PPOCRLabel让模型下载完成然后找到模型目录一般是C:\Users\用户名\.paddleocr\whl\det\ C:\Users\用户名\.paddleocr\whl\rec\把整个.paddleocr目录复制到打包输出目录下并设置环境变量import os os.environ[PADDLE_OCR_HOME] os.path.join(os.path.dirname(os.path.abspath(__file__)), .paddleocr)这个方案的好处是离线环境也能用我给客户的最终交付版本采用的就是这种方案用户体验最好。方案二自动下载模式如果目标机器能联网也可以不做任何处理程序启动时会自动下载模型到当前用户目录。但看起来会卡在下载阶段很久网络不好的话还可能下载失败体验很糟糕。方案三自定义模型路径如果你有自己训练或者微调过的模型可以在PPOCRLabel界面里指定模型路径或者在启动参数里传--det_model_dir等参数。这个方案灵活性最高适合算法团队内部使用。4.2 路径编码问题打包后的exe如果放在包含中文路径的目录下运行部分Windows系统会报编码错误这个坑我必须单独提一下。因为PyInstaller解压临时文件时如果路径含中文可能会导致Paddle相关文件加载失败。建议做法是交付时要求exe文件目录路径为纯英文比如D:\tools\PPOCRLabel或者在程序入口处加一段代码强制设置编码方式import sys import locale sys.stdout.reconfigure(encodingutf-8)这一步看似琐碎但我在现场部署时真的被中文路径问题耽误过半天最后发现就是路径编码的问题。4.3 动态库冲突处理还有一个容易被忽视的问题目标机器上如果安装过其他Python或者PaddlePaddle版本系统PATH中的某些DLL可能会被exe优先加载导致版本冲突。症状是程序启动报一堆奇怪的内存错误或者识别结果明显异常。避免办法是在启动脚本文件PPOCRLabel.bat里先清空当前环境变量再启动exeecho off set PATHC:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem start PPOCRLabel.exe虽然粗暴但确实管用。实际运行时不会影响识别效果同时能屏蔽绝大多数系统环境干扰。5. 打包过程中遇到的问题与排查方法5.1 常用调试手段PPOCRLabel打包后的调试思路不能靠猜要按日志一层层排查。我用得最多的三个手段第一保留控制台输出。打包后先不要关掉console窗口看到报错信息再判断是缺模块还是缺DLL。如果是ModuleNotFoundError说明模块没收集全如果是OSError: [WinError 126]大概率是DLL缺失如果是AttributeError可能是版本不匹配。第二在程序入口处加一层日志输出比如把启动路径、环境变量、关键模块版本都打印出来import logging logging.basicConfig(levellogging.DEBUG, filenamedebug.log) logging.debug(current dir: %s, os.getcwd()) logging.debug(sys.path: %s, sys.path) import paddle logging.debug(paddle version: %s, paddle.__version__)第三用Process Explorer或者Dependency Walker分析exe的DLL依赖确认哪些系统DLL缺失或多余。5.2 常见错误速查表错误现象根本原因解决措施ModuleNotFoundError: No module named paddleocr.utilsPyInstaller漏收集子模块在hiddenimports中显式加入模块名ImportError: DLL load failedVC运行库缺失或paddle动态库未收集安装VC Redistributable用collect_dynamic_libs收集Qt platform plugin not foundPyQt5平台插件缺失在datas中加入plugins/platforms和plugins/imageformats启动后闪退且无任何提示模型文件路径错误或编码问题检查.paddleocr路径设置PADDLE_OCR_HOME环境变量杀毒软件报木马PyInstaller的bootloader特性触发误报更换upx压缩、签名exe、添加白名单说明启动慢、CPU占用高CPU版Paddle推理属于正常现象首次启动时模型加载耐心等待后续会快一些图片打开后无法标注Qt插件中qjpeg等图像格式插件缺失收集PyQt5/plugins/imageformats5.3 杀毒误报问题处理这个必须单独说。PyInstaller打出来的exe在很多杀毒软件眼中天然带有危险特征因为它的bootloader会动态加载Python代码这个行为跟某些恶意软件的特征很像。我第一次打包完发给同事他的电脑直接弹出木马警告当时吓一跳。处理思路分三步走确认exe确实没有被植入任何恶意代码整个打包流程都是自己操作这点可以放心用UPX压缩可能会加剧误报如果被报毒建议关闭UPX重新打包正式交付时联系目标电脑上的安全软件加白名单同时建议用代码签名证书对exe进行数字签名代码签名证书需要购买价格不便宜如果不是商业分发可以跳过。但一定要在交付说明文档里写清楚exe的生成方式和校验值方便客户核对。6. 最终交付形态与体积优化6.1 交付目录结构规划打包完成后dist里的目录非常杂乱直接给客户不合适。我整理了一套干净的交付结构PPOCRLabel_交付包/ │ ├── PPOCRLabel/ # 打包产物目录 │ ├── PPOCRLabel.exe │ ├── _internal/ # PyInstaller5.x后的依赖目录 │ └── ... │ ├── .paddleocr/ # 预下载的模型文件 │ ├── 标注数据/ # 空目录让用户直接放图片 │ ├── 输出结果/ # 空目录标注结果输出位置 │ ├── 使用说明.txt # 一页看懂的操作指引 └── 启动PPOCRLabel.bat # 稳定启动脚本6.2 体积优化实测数据我打包出来的初始版本体积是3.6GB这个体积实在有点大。经过几轮精简后降到1.9GB说下实际做了哪些操作第一排除无用的库。PaddlePaddle会附带大量开发相关文件比如paddle.fluid模块其实已经不怎么用了可以通过spec文件的excludes排除excludes[paddle.fluid, paddle.dataset, matplotlib, PIL.ImageQt]第二关闭UPX虽然体积会略有增大但稳定性更好综合考虑后我又把UPX关掉了。第三压缩模型。PaddleOCR的检测模型和识别模型原始的精度如果太高打包体积会比较大可以在不影响标注效果的前提下换成mobile版模型。实测mobile版模型在标注场景下速度和体积都有优势精度损失基本可忽略。第四PyInstaller版本的选择。5.13.2比4.x版本打出来的包结构更清晰整体体积也更小建议优先用新版。6.3 启动脚本优化最终交付时我不建议让用户直接双击exe因为工作目录不对会引发各种奇怪问题。我在交付包里放了一个启动脚本启动PPOCRLabel.bat内容如下echo off chcp 65001 nul cd /d %~dp0 set PATHC:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem set PADDLE_OCR_HOME%~dp0.paddleocr start %~dp0PPOCRLabel\PPOCRLabel.exe这个脚本做了三件事切换到脚本所在目录、清理系统PATH避免DLL冲突、设置PaddleOCR模型目录。实测下来无论u盘拷贝到哪台电脑双击脚本都能稳定启动。7. 从打包到落地一份属于自己的复盘打包PPOCRLabel这个任务前后花了我一周多时间第一版被打回第二版能在部分电脑跑通但报错不断到第三版才算稳定交付。复盘下来真正影响成败的核心点其实不在打包命令本身而在于对依赖链路的理解和对目标环境的充分预判。比如PaddlePaddle这种重型框架依赖的动态库横跨系统层、Python层、模型层任何一个环节断了都会在别人的电脑上翻车。我在测试阶段准备了三类验证环境一台全新未安装任何开发工具的Windows电脑、一台安装过完整Python环境的电脑、一台安装了安全软件的企业办公电脑。在每台机器上分别做启动测试、图片标注测试、结果导出测试。这个过程很枯燥但能提前暴露绝大多数现场问题。最后再分享一个实操心得打包后的exe如果是在本机跑通先别急着拷给别人最好用虚拟机或者另一台物理机做一次裸机验证。因为本机环境带着开发时安装的各种依赖很多问题根本暴露不出来。这个习惯帮我避免了太多次我这边明明能跑客户那边就是不行的尴尬。本文还有配套的精品资源点击获取
使用PyInstaller将PPOCRLabel打包为Windows exe的完整实践
简介将PPOCRLabel半自动标注工具编译封装为exe程序的资源包面向需要进行OCR数据标注的开发者、算法工程师及项目团队免去安装配置PaddlePaddle环境和各种依赖的繁琐步骤解压后双击即可进入图形化标注界面适合文档扫描、车牌识别、证件信息提取等场景。压缩包共2000个文件以py源码、pyd编译扩展、exe主程序、whl依赖包为主另含部分配置文件、模型参数与示例图片整体大小约355MB目录涵盖运行库与依赖便于用户了解工具构成。工具支持在图像上绘制文字框并录入标注内容可执行撤销、重做、保存等操作并能够导出JSON格式的标注数据与PaddleOCR等主流训练流程兼容同时借助PaddlePaddle生态具备部分自动标注能力能明显提高标注效率。目前该资源已有6445人浏览学习适合从零开始接触OCR训练数据准备的用户也适合追求高效标注的进阶开发者。1. 项目概况与打包思路1.1 为什么要打包PPOCRLabel先说背景。PPOCRLabel是PaddleOCR生态里非常实用的半自动标注工具核心价值是把OCR识别结果直接落到标注框里人工只需要修正错字和漏框能省下大量从零框选的时间。但问题也很现实这个工具跑起来依赖Python环境和PaddlePaddle框架我在实际交付时不止一次遇到以下情况标注团队的同事电脑上没装Python装环境又怕把系统搞乱项目验收方要求提供独立的可视化工具而不是一堆源码加命令行换一台机器就要重新配一遍CUDA、PaddlePaddle、Qt相关依赖时间成本太高所以在一次标注任务中我决定把PPOCRLabel打包成Windows下的exe程序做到双击即用。这篇文章就把完整过程、坑点和最终方案记录下来。1.2 打包方案选型对比在动手之前我把主流方案过了一遍这里直接给出横向对比方便你按自己情况选方案优势劣势适不适合PPOCRLabelPyInstaller文档全、社区案例多、支持hook机制打包体积大、偶尔误报毒首选cx_Freeze相对轻量对PyQt5和PaddlePaddle等动态库处理不如PyInstaller省心备选Nuitka编译为C性能好、不易反编译配置成本高PaddlePaddle这类大型库编译时容易出幺蛾子不推荐Docker封装环境隔离彻底不适合Windows桌面端直接交付不适合本场景综合权衡我选了PyInstaller 单目录模式。为什么不选单文件模式PPOCRLabel依赖PaddleOCR模型文件、Qt相关插件和大量动态库单文件模式每次启动都要解压到临时目录启动速度明显变慢而且在部分企业电脑上更容易被杀毒软件拦截。单目录模式虽然看起来文件多但胜在稳定可控。2. 环境准备与依赖处理2.1 干净环境的重要性强烈建议在干净的Python虚拟环境中进行打包不要直接使用系统Python。原因很直接系统Python里装了太多无关包PyInstaller打包时会尝试把它们一起收集进去导致包体膨胀甚至因为某些包互相冲突导致启动报错。我用的环境如下Windows 10 专业版 22H2Python 3.9.1332位和64位都试过最终用64位毕竟PaddlePaddle对64位支持更好PaddlePaddle 2.5.2CPU版PaddleOCR 2.7.0PPOCRLabel 2.1.3创建虚拟环境的命令很简单python -m venv ppocrlabel_env ppocrlabel_env\Scripts\activate这里有个细节要注意安装PaddlePaddle时不要默认装GPU版除非你确认目标机器都有NVIDIA显卡且CUDA环境完整。否则打包出来在别人电脑上跑不起来反而麻烦。纯CPU版本虽然推理慢一些但标注场景下人工修正占大头速度完全够用。2.2 依赖安装顺序有讲究依赖安装顺序会直接影响最终exe能否正常运行这绝对是我踩出来的经验。建议按以下顺序来pip install paddlepaddle2.5.2 pip install paddleocr2.7.0 pip install PPOCRLabel2.1.3为什么要按这个顺序因为PPOCRLabel安装时会自动检测PaddleOCR和PaddlePaddle的版本如果先装PPOCRLabel它可能拉取到某些不兼容的版本组合。装完以后执行一下PPOCRLabel --lang ch如果程序能正常启动说明环境基本OK再继续打包流程。这一步很有必要别急着打包先确认源码能跑打包后的排查范围才会小。2.3 补装PyInstaller和必要的辅助工具pip install pyinstaller5.13.2 pip install pyinstaller-hooks-contribpyinstaller-hooks-contrib一定要装里面包含了PaddlePaddle、PyQt5等常用库的打包hook没有它很多动态库不会自动收集。装完以后最好检查一下hooks是否真的包含paddle相关条目python -c from PyInstaller.utils.hooks import get_hook_config; print(hooks ok)这个检测不复杂但能提前发现hook缺失问题省得后面打包出来运行报错再回头查。3. 基于spec文件的精细化打包流程3.1 编写PPOCRLabel专属spec文件PyInstaller不推荐直接写一长串命令行参数更好的做法是编写spec文件它能把所有打包配置固化下来后面要调整只需要改spec文件重新执行一次构建非常方便。我最终使用的spec文件核心内容如下# -*- mode: python ; coding: utf-8 -*- from PyInstaller.utils.hooks import collect_data_files, collect_submodules datas [] binaries [] hiddenimports [] # 收集PaddleOCR和PPOCRLabel相关数据文件 datas collect_data_files(paddleocr) datas collect_data_files(PPOCRLabel) datas collect_data_files(paddle) # 收集动态链接库尤其是paddle相关 binaries collect_dynamic_libs(paddle) binaries collect_dynamic_libs(paddleocr) # 隐藏导入 hiddenimports collect_submodules(paddleocr) hiddenimports collect_submodules(PPOCRLabel) hiddenimports collect_submodules(paddle) a Analysis( [PPOCRLabel.py], pathex[], binariesbinaries, datasdatas, hiddenimportshiddenimports, hookspath[], hooksconfig{}, runtime_hooks[], excludes[matplotlib, PIL.ImageQt], noarchiveFalse, ) pyz PYZ(a.pure) exe EXE( pyz, a.scripts, exclude_binariesTrue, namePPOCRLabel, debugFalse, bootloader_ignore_signalsFalse, stripFalse, upxTrue, consoleTrue, iconapp.ico, ) coll COLLECT( exe, a.binaries, a.datas, stripFalse, upxTrue, namePPOCRLabel, )注意几个细节upxTrue默认开启但如果安装的UPX版本不兼容某些库反而会损坏二进制文件建议实测后再决定是否开UPXconsoleTrue保留命令行窗口我在开发阶段保留它正式交付时改成consoleFalse避免弹出黑框影响体验iconapp.ico编译前的图标文件需要256x256以上的ico格式直接改后缀名没用3.2 执行打包并查看日志pyinstaller PPOCRLabel.spec --clean --noconfirm打包过程大概需要5到15分钟取决于机器性能。日志出现以下内容说明关键库都被收集到了INFO: Processing pre-safe-import-module hook paddleocr INFO: Processing module hooks... INFO: Loading module hook hook-paddle.py... INFO: Loading module hook hook-paddleocr.py...打包完成后dist目录下会生成PPOCRLabel文件夹里面包含exe主程序和大量依赖文件。但仅仅解压出来能放到别人电脑上用还差得远接下来才是最关键的验证和补缺阶段。3.3 首次启动验证与常见启动崩溃修复双击exe大概率会遇到问题。我首次打包后的经历比较典型启动直接报错ModuleNotFoundError: No module named paddleocr.utils这个错误出现的主要原因是PyInstaller在某些情况下没有完整收集paddleocr的内部子模块。解决办法有两个思路第一个思路是在spec文件的hiddenimports里强制指定hiddenimports [ paddleocr.utils, paddleocr.tools, paddleocr.parser, ppocrlabel.utils, ]第二个思路是在程序入口处加上显式导入。这个方法百试百灵因为显式import过的模块PyInstaller在静态分析阶段就会收入依赖import paddleocr.utils import paddleocr.tools import paddleocr.parser import ppocrlabel.utils两个方法可以一起做因为实在不想打包完才发现漏了某个子模块又要重新打包浪费时间。除了ModuleNotFoundError还有两类非常常见的启动崩溃DLL load failed while importing paddle大概率是VC运行库缺失需要在目标机器上安装VC Redistributableqt.qpa.plugin: Could not find the Qt platform plugin windows这是Qt平台插件没被正确收集需要在spec里加platform plugin路径针对Qt插件问题在spec里显式指定from PyInstaller.utils.hooks import collect_data_files qt_plugins collect_data_files(PyQt5, includes[Qt/plugins/platforms/*, Qt/plugins/imageformats/*]) datas qt_plugins重新打包后再启动程序能正常进入主界面但深坑还在后面模型文件路径问题。4. 模型文件路径与运行环境适配4.1 PaddleOCR模型位置的三种方案PPOCRLabel启动时PaddleOCR会自动下载检测模型和识别模型到用户目录的.paddleocr文件夹。但在打包后的exe环境中程序的工作目录、临时目录和用户目录都跟源码模式不同所以模型文件经常找不到要么就是每次启动都在尝试重新下载。处理这个问题的方案有三种我按推荐程度排序方案一预下载模型并随包分发在源码模式下先手动运行一次PPOCRLabel让模型下载完成然后找到模型目录一般是C:\Users\用户名\.paddleocr\whl\det\ C:\Users\用户名\.paddleocr\whl\rec\把整个.paddleocr目录复制到打包输出目录下并设置环境变量import os os.environ[PADDLE_OCR_HOME] os.path.join(os.path.dirname(os.path.abspath(__file__)), .paddleocr)这个方案的好处是离线环境也能用我给客户的最终交付版本采用的就是这种方案用户体验最好。方案二自动下载模式如果目标机器能联网也可以不做任何处理程序启动时会自动下载模型到当前用户目录。但看起来会卡在下载阶段很久网络不好的话还可能下载失败体验很糟糕。方案三自定义模型路径如果你有自己训练或者微调过的模型可以在PPOCRLabel界面里指定模型路径或者在启动参数里传--det_model_dir等参数。这个方案灵活性最高适合算法团队内部使用。4.2 路径编码问题打包后的exe如果放在包含中文路径的目录下运行部分Windows系统会报编码错误这个坑我必须单独提一下。因为PyInstaller解压临时文件时如果路径含中文可能会导致Paddle相关文件加载失败。建议做法是交付时要求exe文件目录路径为纯英文比如D:\tools\PPOCRLabel或者在程序入口处加一段代码强制设置编码方式import sys import locale sys.stdout.reconfigure(encodingutf-8)这一步看似琐碎但我在现场部署时真的被中文路径问题耽误过半天最后发现就是路径编码的问题。4.3 动态库冲突处理还有一个容易被忽视的问题目标机器上如果安装过其他Python或者PaddlePaddle版本系统PATH中的某些DLL可能会被exe优先加载导致版本冲突。症状是程序启动报一堆奇怪的内存错误或者识别结果明显异常。避免办法是在启动脚本文件PPOCRLabel.bat里先清空当前环境变量再启动exeecho off set PATHC:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem start PPOCRLabel.exe虽然粗暴但确实管用。实际运行时不会影响识别效果同时能屏蔽绝大多数系统环境干扰。5. 打包过程中遇到的问题与排查方法5.1 常用调试手段PPOCRLabel打包后的调试思路不能靠猜要按日志一层层排查。我用得最多的三个手段第一保留控制台输出。打包后先不要关掉console窗口看到报错信息再判断是缺模块还是缺DLL。如果是ModuleNotFoundError说明模块没收集全如果是OSError: [WinError 126]大概率是DLL缺失如果是AttributeError可能是版本不匹配。第二在程序入口处加一层日志输出比如把启动路径、环境变量、关键模块版本都打印出来import logging logging.basicConfig(levellogging.DEBUG, filenamedebug.log) logging.debug(current dir: %s, os.getcwd()) logging.debug(sys.path: %s, sys.path) import paddle logging.debug(paddle version: %s, paddle.__version__)第三用Process Explorer或者Dependency Walker分析exe的DLL依赖确认哪些系统DLL缺失或多余。5.2 常见错误速查表错误现象根本原因解决措施ModuleNotFoundError: No module named paddleocr.utilsPyInstaller漏收集子模块在hiddenimports中显式加入模块名ImportError: DLL load failedVC运行库缺失或paddle动态库未收集安装VC Redistributable用collect_dynamic_libs收集Qt platform plugin not foundPyQt5平台插件缺失在datas中加入plugins/platforms和plugins/imageformats启动后闪退且无任何提示模型文件路径错误或编码问题检查.paddleocr路径设置PADDLE_OCR_HOME环境变量杀毒软件报木马PyInstaller的bootloader特性触发误报更换upx压缩、签名exe、添加白名单说明启动慢、CPU占用高CPU版Paddle推理属于正常现象首次启动时模型加载耐心等待后续会快一些图片打开后无法标注Qt插件中qjpeg等图像格式插件缺失收集PyQt5/plugins/imageformats5.3 杀毒误报问题处理这个必须单独说。PyInstaller打出来的exe在很多杀毒软件眼中天然带有危险特征因为它的bootloader会动态加载Python代码这个行为跟某些恶意软件的特征很像。我第一次打包完发给同事他的电脑直接弹出木马警告当时吓一跳。处理思路分三步走确认exe确实没有被植入任何恶意代码整个打包流程都是自己操作这点可以放心用UPX压缩可能会加剧误报如果被报毒建议关闭UPX重新打包正式交付时联系目标电脑上的安全软件加白名单同时建议用代码签名证书对exe进行数字签名代码签名证书需要购买价格不便宜如果不是商业分发可以跳过。但一定要在交付说明文档里写清楚exe的生成方式和校验值方便客户核对。6. 最终交付形态与体积优化6.1 交付目录结构规划打包完成后dist里的目录非常杂乱直接给客户不合适。我整理了一套干净的交付结构PPOCRLabel_交付包/ │ ├── PPOCRLabel/ # 打包产物目录 │ ├── PPOCRLabel.exe │ ├── _internal/ # PyInstaller5.x后的依赖目录 │ └── ... │ ├── .paddleocr/ # 预下载的模型文件 │ ├── 标注数据/ # 空目录让用户直接放图片 │ ├── 输出结果/ # 空目录标注结果输出位置 │ ├── 使用说明.txt # 一页看懂的操作指引 └── 启动PPOCRLabel.bat # 稳定启动脚本6.2 体积优化实测数据我打包出来的初始版本体积是3.6GB这个体积实在有点大。经过几轮精简后降到1.9GB说下实际做了哪些操作第一排除无用的库。PaddlePaddle会附带大量开发相关文件比如paddle.fluid模块其实已经不怎么用了可以通过spec文件的excludes排除excludes[paddle.fluid, paddle.dataset, matplotlib, PIL.ImageQt]第二关闭UPX虽然体积会略有增大但稳定性更好综合考虑后我又把UPX关掉了。第三压缩模型。PaddleOCR的检测模型和识别模型原始的精度如果太高打包体积会比较大可以在不影响标注效果的前提下换成mobile版模型。实测mobile版模型在标注场景下速度和体积都有优势精度损失基本可忽略。第四PyInstaller版本的选择。5.13.2比4.x版本打出来的包结构更清晰整体体积也更小建议优先用新版。6.3 启动脚本优化最终交付时我不建议让用户直接双击exe因为工作目录不对会引发各种奇怪问题。我在交付包里放了一个启动脚本启动PPOCRLabel.bat内容如下echo off chcp 65001 nul cd /d %~dp0 set PATHC:\Windows\System32;C:\Windows;C:\Windows\System32\Wbem set PADDLE_OCR_HOME%~dp0.paddleocr start %~dp0PPOCRLabel\PPOCRLabel.exe这个脚本做了三件事切换到脚本所在目录、清理系统PATH避免DLL冲突、设置PaddleOCR模型目录。实测下来无论u盘拷贝到哪台电脑双击脚本都能稳定启动。7. 从打包到落地一份属于自己的复盘打包PPOCRLabel这个任务前后花了我一周多时间第一版被打回第二版能在部分电脑跑通但报错不断到第三版才算稳定交付。复盘下来真正影响成败的核心点其实不在打包命令本身而在于对依赖链路的理解和对目标环境的充分预判。比如PaddlePaddle这种重型框架依赖的动态库横跨系统层、Python层、模型层任何一个环节断了都会在别人的电脑上翻车。我在测试阶段准备了三类验证环境一台全新未安装任何开发工具的Windows电脑、一台安装过完整Python环境的电脑、一台安装了安全软件的企业办公电脑。在每台机器上分别做启动测试、图片标注测试、结果导出测试。这个过程很枯燥但能提前暴露绝大多数现场问题。最后再分享一个实操心得打包后的exe如果是在本机跑通先别急着拷给别人最好用虚拟机或者另一台物理机做一次裸机验证。因为本机环境带着开发时安装的各种依赖很多问题根本暴露不出来。这个习惯帮我避免了太多次我这边明明能跑客户那边就是不行的尴尬。本文还有配套的精品资源点击获取