简介PPOCRLabel是PaddlePaddle OCR项目中的半自动标注工具本资源将其完整打包为可直接运行的exe程序面向需要训练OCR模型的数据标注人员与AI开发者解决本地环境配置复杂、上手门槛高的问题。压缩包内共2000个文件约355MB围绕exe启动器配备了Python源码、编译后的pyd模块、依赖dll、动态库以及必要的配置文件用户无需预装PaddlePaddle或特定开发环境解压即用可快速进入标注流程。该工具支持在图像上拖拽绘制文本框、录入文字内容并提供撤销、重做与保存功能标注结果可导出为json格式无缝衔接PaddlePaddle及其他主流深度学习框架的模型训练。由于不需要手动搭建环境尤其适合非专业用户、初创团队及文字识别应用开发者目前已有6445人学习下载是降低OCR数据准备成本、提高标注效率的实用资源。 做了几年OCR相关的数据工作手边一直留着一个工具叫 PPOCRLabel它是 PaddleOCR 生态里的半自动标注工具。凡是做 OCR 模型训练的人基本都用它标注过数据模型先跑一遍检测和识别把结果预置到界面上人只需要改一改错框和漏框导出标注结果即可。工具确实好用但一直有个尴尬的地方——每次要让别人用都得从头搭环境。装 Python、装 PaddlePaddle、处理各种 Visual C 运行库问题一套下来至少半小时遇到不太懂代码的同事基本就是灾难。所以我就把 PPOCRLabel 打包成了 exe 程序目标是实现“双击就能进入标注界面”。这篇博文就是记录我踩过的所有坑包括 PyInstaller 的 spec 文件怎么写、资源文件怎么收集、几个常见报错怎么解决以及 exe 交到别人手里后在 Windows 和国产 Linux 系统上可能遇到什么问题。如果你也在做 OCR、标注工具或者任何 PyQt 深度学习推理项目的分发这篇文章能帮你省掉至少一个下午的排错时间。1. 先想清楚什么场景真的需要把 PPOCRLabel 打成 exe1.1 给队友分发工具远比你想的费时PPOCRLabel 运行时依赖 PaddlePaddle、PaddleOCR、PyQt5、shapely、opencv 这一大串库。每个使用者单独安装一次就是一次环境调试过程有人 Python 版本不对有人 pip 下载超时有人缺 Visual C 运行库有人装错了 CPU 版和 GPU 版 Paddle。我统计过一个团队五六个成员光“帮忙装环境”就能吃掉一整天工时。更麻烦的是标注工具不只是自己用很多时候要交给临时标注员或者外包团队做数据生产。那个场景下根本不可能让对方先学 Python 和 conda。如果你只是自己开发机上用那确实没必要折腾打包但只要你需要把工具交给别人哪怕只有一个同事打包成 exe 都是划算的。一次打包半小时到一小时换来的是一劳永逸的“绿色版”工具。1.2 三种交付方式对比源码、Docker、exe我最初也考虑过另外两条路源码安装和 Docker但后来都放弃了。源码安装conda 可以解决一部分问题但标注团队的电脑通常没有 conda也不会看报错信息。库冲突之后基本无法自行恢复最后还是要回来找你。Docker依赖隔离确实干净但 GUI 程序跑 Docker 很别扭Windows 上需要容器桌面支持Linux 上要配置 X11 转发。标注团队电脑配置参差不齐有老电脑根本跑不动 Docker。exe 打包体积大是最大缺点但使用者零成本上手双击就运行。只要把打包过程里那点坑踩完后面就是“开发机打包一次团队长期复用”。排除掉 Docker 之后用 PyInstaller 打包 exe 就成了分发 Windows 桌面工具最主流、最省心的方案。1.3 PPOCRLabel“三合一”的特殊打包结构给 PPOCRLabel 做打包和普通 PyQt 程序不一样它其实是三块耦合在一起的东西PyQt5 GUI负责标注界面和交互。界面目录下有 resources 文件夹包含图标、样式表、默认配置等打包时必须作为数据文件收集进去。PaddleOCR 推理引擎包含 PaddlePaddle 运行时和 OCR 检测、识别、方向分类模型。PaddlePaddle 内部有大量 C 动态库和 Python 子模块PyInstaller 的静态扫描经常漏。半自动标注的本地服务部分版本和功能依赖 Flask-SocketIO 启动本地 WebSocket 服务PyInstaller 对这类框架的动态加载支持不友好默认打包模式很容易触发 async_mode 之类的问题。这三块互相影响所以打包不能指望 PyInstaller 的默认扫描必须在 spec 文件里显式指定 hidden imports、datas 和二进制库目录。2. 打包第一步其实是把环境锁死2.1 Python 版本别追求新3.8 和 3.10 最稳我第一次打包时图新鲜用了 Python 3.11结果 PaddlePaddle 的 wheel 当时还没跟上安装阶段直接报错连包都打不了。后来退回到 3.8一次通过。建议直接用 conda 创建全新环境conda create -n ppocrlabel python3.8 -y conda activate ppocrlabel这里多说一句Python 必须是 64 位。32 位 Python 在装 PaddlePaddle 和 PyQt5 的时候问题非常多而且内存受限标注大尺寸图片时容易崩。2.2 版本对应关系 paddlepaddle、paddleocr、PPOCRLabel这一步最容易翻车。PPOCRLabel 对 PaddleOCR 有版本要求PaddleOCR 又对 PaddlePaddle 有版本要求三个版本必须互相匹配。我验证过的稳定组合是PPOCRLabel 2.1.2paddleocr 2.6.1paddlepaddle 2.4.2CPU 版PaddleOCR 2.6 要求 paddlepaddle 大于等于 2.4但 paddlepaddle 升到 2.5 之后又有一些 API 变化可能导致 PPOCRLabel 在运行时识别报错。所以最稳妥的办法是装完这组版本之后立刻执行一条命令pip freeze requirements_lock.txt把这个文件保存下来写进项目仓库。以后换机器或者重新打包直接按这个文件装依赖版本就不会漂移。千万不要在打包前顺手执行 pip install --upgrade我踩过这个坑升完 PaddleOCR 后整个标注流程直接罢工。2.3 验证源码能跑通再谈打包打包最忌讳“功能还没走通就开工”。源码模式下如果工具本身有问题打包出来的 exe 只会把问题原封不动带过去而且排错更困难。所以第一步永远是先在虚拟环境里启动一次cd PPOCRLabel python PPOCRLabel.py --lang ch确认窗口能打开、能加载图片、能识别、能导出标注然后再进入打包流程。同时把这个步骤控制台的日志输出保存下来特别是正常启动时的日志格式后面 exe 出问题时可以对照排查。另外如果目标机器没有 NVIDIA 显卡建议直接用 CPU 版 PaddlePaddle 打包或者在代码里设置环境变量 CUDA_VISIBLE_DEVICES-1 强制不加载 GPU。GPU 版打包后体积更大而且在没有对应 CUDA 运行库的机器上初始化会异常缓慢甚至卡死。3. 用 spec 文件打包而不是裸敲命令行3.1 为什么不推荐用命令行参数很多人打包 PyQt 应用时习惯直接用命令pyinstaller -F -w PPOCRLabel.py这种简洁方式对纯 PyQt 程序勉强够用但 PPOCRLabel 这种依赖 PaddleOCR 的复杂项目就不行了。命令行方式只能加两三个额外文件或模块而 PPOCRLabel 需要处理几十个 hidden imports、多个数据目录、一堆二进制库。参数一旦写错重新执行命令等于从头再来。更合理的做法是先让 PyInstaller 生成一个 spec 文件之后所有配置都在 spec 里面管理。spec 文件本身就是一个 Python 脚本可以写变量、路径拼接、调用收集函数每次打包都复用同一份配置升级后也只需修少量路径和版本号。3.2 一份能跑通的 PPOCRLabel.spec 配置下面这份配置是我实际使用并验证过的省略了一些和本机强相关的路径但核心结构都在# PPOCRLabel.spec # -*- mode: python ; coding: utf-8 -*- import sys sys.setrecursionlimit(5000) block_cipher None # 项目目录按实际情况修改 project_dir rD:\\work\\PPOCRLabel a Analysis( [project_dir \\PPOCRLabel.py], pathex[project_dir], binaries[ # PaddlePaddle 的动态库目录必须整体收集 (rC:\\Python38\\Lib\\site-packages\\paddle\\libs, paddle\\libs), ], datas[ # PPOCRLabel 界面的资源目录必须带上 (project_dir \\resources, resources), ], hiddenimports[ paddleocr, paddle, skimage, imgaug, pyclipper, shapely, PIL, PyQt5.QtSvg, PyQt5.QtPrintSupport, flask_socketio, engineio, socketio, ], hookspath[], runtime_hooks[], excludes[matplotlib.tests, PIL.ImageTk], win_no_prefer_redirectsFalse, win_private_assembliesFalse, cipherblock_cipher, ) pyz PYZ(a.pure, a.zipped_data, cipherblock_cipher) exe EXE( pyz, a.scripts, a.binaries, a.zipfiles, a.datas, [], namePPOCRLabel, debugFalse, bootloader_ignore_signalsFalse, stripFalse, upxFalse, upx_exclude[], runtime_tmpdirNone, consoleFalse, iconproject_dir \\resources\\icon.ico, )几个细节要特别说明sys.setrecursionlimit(5000) 不是摆设。PyInstaller 在分析 Paddle 这种超大依赖时会触发 RecursionError不调大递归限制直接打包失败。paddle 的库目录用 binaries 整目录带进去不靠 hiddenimports。Paddle 核心是 C 动态库Python 静态扫描根本扫不到。resources 目录不能漏。少了它打包后的 exe 界面找不到图标、样式表很多初始化逻辑会直接崩。如果你用的 PPOCRLabel 版本没有启用 Flask-SocketIO 功能hiddenimports 里那段可以去掉但如果出现 async_mode 报错就需要这个配置配合源码修改下一部分详述。3.3 模型与资源文件的“离线预置”思路PPOCRLabel 第一次运行时会自动下载模型。exe 交给使用者之后如果对方处于内网环境程序会卡在“下载模型”阶段而且没有任何明确提示非常容易被认为“程序坏了”。解决方法是在打包前先把模型下载好然后随分发包一起预置。Windows 上 PaddleOCR 2.x 的默认模型位置是C:\Users\用户名\.paddlex\我在开发机上跑通一次让模型完整下载到本地然后把整个 .paddlex 目录复制出来写一个 install_models.bat 脚本echo off xcopy /E /I /Y .paddlex %USERPROFILE%\.paddlex echo Models installed to %USERPROFILE%\.paddlex pause这样使用者拿到文件夹后先双击这个脚本把模型放到本机再双击 PPOCRLabel.exe 就能离线识别。如果团队针对特定场景训练过自己的检测或识别模型同样把这个自定义模型目录预置到对应位置。4. 四个让 exe 起不来的经典坑与排查链路4.1 invalid async_modeflask_socketio 在冻结环境下的诡异报错这个报错在打包过 flask_socketio 程序的人眼里应该不陌生报错信息大概是ValueError: invalid async_mode原因并不复杂flask_socketio 初始化时会根据环境里是否安装了 eventlet、gevent 来自动选择异步模式默认顺序是 eventlet 优先gevent 其次最后才是 threading。源码模式跑得通是因为开发环境里装了 eventlet 或 geventPyInstaller 打包时没有把这些模块的依赖链完整收集exe 运行时找不到它们async_mode 就变成了非法值。排查链路建议这样走先看报错堆栈定位是哪个文件里创建了 SocketIO 实例。打开源码找到类似 socketio SocketIO(app) 的位置改成socketio SocketIO(app, async_modethreading)threading 模式不依赖 eventlet 和 gevent在打包环境里最稳。 3. 改完源码后必须重新打包。我遇到过有人只改了开发机源码没重新执行 PyInstaller然后对着旧 exe 白排查了半天。如果在修改源码后还想保留更快的异步模式可以在 hiddenimports 里补上 eventlet 和 dns但经验是 threading 已经足够满足标注工具的并发需求没必要徒增体积。4.2 资源文件路径失效界面图标丢失exe 能正常启动但界面上图标全丢或者提示找不到样式表、找不到默认图片这类问题百分之百是 datas 没收集 resources 目录或者代码里的相对路径写死了。PyInstaller 打包后程序运行时的工作目录不一定是你 exe 所在的目录。在 --onefile 模式下程序会先把所有内容解压到系统临时目录相对路径指向的全是临时目录下的路径自然找不到资源。通用解决方法是写一个路径修正函数import sys import os def resource_path(relative_path): base_path getattr(sys, _MEIPASS, os.path.abspath(.)) return os.path.join(base_path, relative_path)然后把 PPOCRLabel 源码里所有指向 resources/xxx 的相对路径替换成 resource_path(resources/xxx)。这个经验不只适用于 PPOCRLabel任何 PyQt 程序打包出现资源丢失都可以这样处理。4.3 PaddleOCR 初始化卡死或无响应卡死比报错更折磨人。常见原因有两个一个是 PaddlePaddle 初始化时尝试检测显卡。目标机器有 NVIDIA 显卡但驱动或 CUDA 版本不匹配初始化过程会异常缓慢甚至卡在检测阶段。最简单粗暴的处理是强制禁用 GPUimport os os.environ[CUDA_VISIBLE_DEVICES] -1一行代码放在程序入口最前面让 Paddle 直接走 CPU 推理。对于标注场景来说CPU 推理虽然慢一点但胜在稳定团队里任何电脑都能跑。另一个原因是首次运行联网下载模型内网环境一直卡在 HTTP 申请阶段。这个过程不报错只表现为“白屏几分钟”你打开任务管理器看 CPU 占用和网络流量就能确认。解决办法就一句话按第 3.3 节的方式提前预置模型。4.4 双击 exe 却弹出记事本打开方式被篡改这个现象我一开始也以为是打包出了问题后来才发现是 Windows 层面的“exe 打开方式”被第三方软件改掉了。表现是双击 exe 会弹出记事本或者弹出“选择打开方式”的对话框。处理顺序是右键 exe选“打开方式”再选“Windows 资源管理器”或“始终使用此应用打开”。如果无效打开注册表编辑器定位到 HKEY_CLASSES_ROOT.exe确认默认值是 exefile。再定位到 HKEY_CLASSES_ROOT\exefile\shell\open\command确认默认值是 %1 %*。修改注册表之前先备份当前项改错会导致更严重的问题。这个坑虽然不常见但一旦命中用户很容易误以为“exe 程序坏了”然后发消息来问你。排查 exe 问题前先排除这个可能能省很多沟通成本。5. exe 交到别人手里后部署环境比打包环境更考验人5.1 在 Windows 机器上的首启检查清单把 exe 发给同事前我强烈建议先在自己虚拟机上模拟一遍“干净环境”。Windows 10 或 11 全新虚拟机不装 Python、不装任何运行库直接放进去跑。重点检查这几项双击后窗口是否正常弹出有没有提示缺少 DLL。如果提示缺少 VCRUNTIME140.dll说明目标机器没有 Visual C 运行库打包时要考虑带上 VC_redist.x64.exe或者让对方安装常用运行库合集。断网状态下能否加载图片并识别。这一步能验证模型预置是否成功。杀毒软件有没有拦截尤其是 Windows Defender。PyInstaller 打包的 exe 被误报是常见现象见 5.3。高分屏下的显示效果。如果对方是 2K/4K 显示器PyQt5 界面可能出现模糊。需要在源码 main 函数最前面加两行QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True) QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True)不加这两行exe 在高分屏上会显得又小又糊。5.2 在统信 UOS 等 Linux 系统上收到“exe 安装失败”怎么处理这个问题的搜索热度很高。现象是系统提示“正在安装 exe 程序”然后一直卡住重试也不行。这里需要明确一个基本事实exe 是 Windows PE 格式的可执行文件在 Linux 系统上无法原生运行。统信 UOS 如果提示“正在安装 exe”说明系统尝试用 wine 兼容层去加载最终失败通常是因为 wine 环境不完整或者 exe 依赖的 PaddlePaddle 动态库无法被 wine 正确解析。技术上的正确处理是如果目标机器跑的就是 UOS不要分发 exe。可以分发现成的 Python 源码安装包或者在同一环境下用 PyInstaller 打 Linux 版可执行文件。把标注工具部署成 Windows 远程桌面服务也不失为一种办法但那属于另一套工程体系。不要在 wine 上死磕 PPOCRLabel。简单的工具可能还能跑这种带深度学习推理库的 GUI 程序wine 方案几乎注定失败投入产出比极低。跨平台分发的最省心做法就是“一套业务代码分别在 Windows 和 Linux 下各打一次包”而不是指望一个 exe 通吃所有系统。5.3 杀毒软件误报与代码签名PyInstaller 打包的 exe 被误报病毒的概率不低原理是 PyInstaller 的 bootloader 会把程序代码压缩并在运行时自解压这种自解压行为和某些木马很像。再加上 PaddlePaddle 加载模型动态库的操作也会触发杀毒软件的敏感扫描。实操建议是分场景处理内部团队使用直接把 exe 加入杀毒软件白名单或者通过公司 IT 统一下发。对外分发建议购买代码签名证书对 exe 做数字签名。签名后 Windows SmartScreen 的警告会消失误报率也大幅下降。不要为了减小体积用 UPX 压缩。UPX 是误报重灾区实测压缩后报毒率明显上升代价还只是省了几十 MB完全不划算。6. 把 exe 从能用做到好用体积、启动速度、日常维护6.1 onefile 和 onedir启动速度的取舍我第一次打包用的是 -F 参数打成单个 exe 文件。分发确实方便但实际体验不好每次双击运行PyInstaller 要把几百 MB 的内容解压到系统临时目录启动可能要等十几秒杀毒软件还会在启动时扫描解压过程时间更长。后来我改成了 onedir 模式发布一个文件夹里面是 PPOCRLabel.exe 加 _internal 目录。启动速度快很多因为不再需要解压。虽然多了一个目录但对使用者来说仍然是“双击 exe 就用”学习成本没有增加。如果你确实需要单个文件分发给外部客户建议加一个启动等待界面或者提示“正在初始化请稍候”否则用户会以为程序没反应。6.2 体积失控的原因与瘦身手段PPOCRLabel 打包后 CPU 版大概 600MB 到 900MBGPU 版轻松破 1.5GB。主要占体积的是这么几块PaddlePaddle 的 C 动态库在 paddle/libs 目录下这是大头。PaddleOCR 自带的通用模型文件。opencv、PyQt5、scipy、scikit-image 等常规依赖。我采用的瘦身手段是明确安装 CPU 版 paddlepaddle在 spec 里只打包必要库不覆盖 GPU 相关文件。在 spec 的 excludes 里排除用不到的库比如 matplotlib.tests、tkinter、pytest。注意不要盲目排除 opencvPaddleOCR 底层图像处理依赖它。模型文件不打进 exe 内部以外部文件形式随包分发。这样模型有更新时只要替换模型目录不用重新打整个包。用 onedir 模式而不是 onefileonedir 不把大量文件压缩到单文件里体积本来就比 onefile 小启动也快。第一次打包不要追求瘦身先打一个完整版本跑通之后再逐步精简。PyInstaller 打包时会在 build 目录下生成 warn-PPOCRLabel.txt 文件里面记录了所有缺失模块排查依赖问题先看这个文件。6.3 每次升级 PPOCRLabel 后怎么重新打包PPOCRLabel 还在快速迭代升级版本后重新打包是常态。我有几个固定习惯把 spec 文件、requirements_lock.txt、打包脚本统一放在项目目录下的 build_tools 文件夹里和源码一起纳入版本控制。每次打包前先执行一条命令清理缓存pyinstaller --clean PPOCRLabel.spec不清理的话旧缓存可能会把已经卸载的模块带进新包。打完包之后在干净虚拟机上做一次完整的冒烟测试双击、打开图片、识别、导出标注整个过程走一遍。记录每次打包的代码分支和版本号。这个记录很关键不然半年后看到一个 exe你根本不知道它对应的是哪版代码。最后说一点个人的实操体会。打包 PPOCRLabel 这个 exe最花时间的不是跑出 exe 本身而是模型预置、资源路径处理、部署环境兼容这三件事。把这三件事处理干净exe 才是真正“可交付”的状态。如果你的团队已经有几个人在用 PPOCRLabel建议抽一天时间把 spec 文件和打包脚本整理好以后每次升级只改版本号就能重新分发这是长期来看最划算的一笔投入。本文还有配套的精品资源点击获取