简介：这是一份面向无Python环境用户的PaddleOCR离线文字识别工具打包资源，适合需要将OCR能力部署到Windows端、仅凭图片路径即可获取识别结果的开发者与运维人员。压缩包共2000个文件，约279.22MB，以319个py源码、319个pyc字节码、232个pyd扩展模块和139个dll动态库为核心，构成完整的Python运行时与PaddleOCR依赖；另有57个txt说明、25个png与11个gif示例图、10个ini配置及大量时区数据文件，保证离线环境下的稳定运行。已有3786人学习下载。资源内含可直接运行的exe工具与配套脚本，读者能获得从模型调用、图片路径输入到结果写入txt的完整链路，并参考错误处理、批量识别与界面优化思路，快速搭建属于自己的离线OCR工具。
1. 把 PaddleOCR 塞进一个 exe：离线场景下最省心的交付方式
上个月帮一个做仓储盘点的朋友处理过一件事：他们仓库里十几台 Windows 工控机，网络是内网隔离的，装不了 Python，更别提 pip 在线拉依赖。需求很朴素——拍一张货架标签照片，识别出上面的物料编号。这种场景下，把 PaddleOCR 打包成一个双击就能跑的 exe，几乎是唯一能让现场人员接受的交付形态。PaddleOCR 本身是百度开源的 OCR 工具库，中文识别效果在开源方案里属于第一梯队，支持检测、方向分类、识别三段式流水线，也能直接调PaddleOCR类一把梭。但它的依赖链不轻：PaddlePaddle 推理库、模型文件、OpenCV、numpy、shapely、pyclipper 一大串，直接pyinstaller打包十有八九会翻车。这篇笔记就围绕「PaddleOCR 打包 exe 离线工具」这件事，把选型、打包脚本、模型外置、路径处理、体积裁剪和常见报错一条条拆开讲，目标是你照着能复现出一个在无网 Windows 上稳定运行的识别工具。适合两类人：一类是要给客户或现场交付离线 OCR 能力的工程师，另一类是自己想把 PaddleOCR 做成桌面小工具、又不想被环境问题反复折磨的开发者。
2. 打包前的技术选型：PyInstaller、模型外置与推理引擎
2.1 为什么默认推荐 PyInstaller 而不是 Nuitka
Python 转 exe 的常见方案有 PyInstaller、cx_Freeze、Nuitka、py2exe 几种。PaddleOCR 这种带大量 C 扩展和动态库的项目，我一般会先上 PyInstaller，原因是它对二进制依赖的收集逻辑最成熟，--collect-all和 hook 机制能省掉大量手工拷贝 dll 的活。Nuitka 编译成真正机器码，启动快、体积小，但它对 Paddle 这种含自定义算子的库兼容性坑更多，编译一次动辄十几分钟，调试成本高。cx_Freeze 配置写起来更啰嗦，社区针对 Paddle 的现成 hook 少。所以除非你对启动速度有硬指标，否则 PyInstaller 是性价比最高的起点。需要提醒的是，PyInstaller 打包出来的不是「编译后的程序」，而是把 Python 解释器和依赖一起塞进一个自解压结构，运行时会在临时目录展开，这一点直接决定了后面模型路径和资源定位的写法。
2.2 模型外置还是打进 exe
PaddleOCR 默认会去下载轻量模型（检测约几 MB、识别约十几 MB、方向分类约 1MB 多），首次运行联网拉取。离线场景绝对不能依赖这个行为，必须把模型文件提前准备好。两种做法：一是把模型目录一起打进 exe，二是模型放在 exe 同级目录外置。我强烈建议外置。原因有三：第一，打包进去会让 exe 体积膨胀，且每次换模型都要重新打包；第二，PyInstaller 单文件模式下资源在临时目录，模型路径容易写错；第三，外置模型方便现场替换成更高精度的服务器版模型。目录结构建议长这样：
ocr_tool/ ├── ocr_tool.exe ├── models/ │ ├── det/ # 检测模型 inference.pdmodel + inference.pdiparams │ ├── rec/ # 识别模型 │ └── cls/ # 方向分类模型 └── config.ini # 可选，放阈值等参数模型文件从 PaddleOCR 官方模型库下载后解压，每个目录里应有inference.pdmodel、inference.pdiparams、inference.pdiparams.info三个文件。识别模型还要带ppocr_keys_v1.txt字典文件，这个字典漏了会直接报 key 数量不匹配。
2.3 推理引擎与依赖版本锁定
PaddleOCR 底层跑的是 PaddlePaddle 推理库，CPU 版就够用，除非现场有 NVIDIA 显卡且愿意装 CUDA。离线交付我基本只用 CPU 版paddlepaddle，不装paddlepaddle-gpu，因为 GPU 版对驱动和 CUDA 版本极其敏感，工控机上大概率没有。版本上要锁死，PaddleOCR 和 PaddlePaddle 的版本兼容关系比较微妙，建议用一组经过验证的组合，比如paddleocr==2.7.x配paddlepaddle==2.5.x，具体以你本地能跑通的为准，锁进requirements.txt。另外opencv-python建议换成opencv-python-headless，省掉 GUI 相关的 dll，打包体积和报错都会少一截。
# 建议在干净虚拟环境里装依赖，避免把无关包打进去 python -m venv venv_ocr venv_ocr\Scripts\activate pip install paddlepaddle==2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple pip install paddleocr==2.7.3 pip install opencv-python-headless pyinstaller这里用清华源是为了装包快，离线机器上不需要。装完后先别急着打包，务必在虚拟环境里跑通一次识别，确认模型能加载、图片能出结果，再进入打包环节。很多打包失败其实是环境本身就没跑通，被误判成打包问题。
3. 打包脚本实操：spec 文件、隐藏导入与资源收集
3.1 先写一个最小可用的识别入口
打包前需要一个明确的入口脚本，不要直接拿 PaddleOCR 的示例改。入口要处理三件事：定位模型目录、初始化 OCR 对象、接收命令行参数或简单 GUI。下面是一个命令行版入口，够用且好调试：
# main.py import os import sys import argparse from paddleocr import PaddleOCR def get_base_dir(): """兼容 PyInstaller 打包后的路径定位""" if getattr(sys, 'frozen', False): # 打包后 exe 所在目录 return os.path.dirname(sys.executable) # 源码运行时的当前文件目录 return os.path.dirname(os.path.abspath(__file__)) def build_ocr(): base = get_base_dir() model_root = os.path.join(base, 'models') ocr = PaddleOCR( use_angle_cls=True, lang='ch', det_model_dir=os.path.join(model_root, 'det'), rec_model_dir=os.path.join(model_root, 'rec'), cls_model_dir=os.path.join(model_root, 'cls'), rec_char_dict_path=os.path.join(model_root, 'rec', 'ppocr_keys_v1.txt'), use_gpu=False, show_log=False, ) return ocr def main(): parser = argparse.ArgumentParser() parser.add_argument('--img', required=True, help='待识别图片路径') args = parser.parse_args() ocr = build_ocr() result = ocr.ocr(args.img, cls=True) for line in result[0] or []: box, (text, score) = line print(f'{text}\t{score:.4f}') if __name__ == '__main__': main()逻辑说明：get_base_dir是关键，sys.frozen是 PyInstaller 运行时注入的标志，打包后必须用sys.executable的目录来定位外置模型，否则会跑到临时解压目录里找不到文件。det_model_dir等参数显式指定模型路径，避免 PaddleOCR 触发自动下载。use_gpu=False强制 CPU。show_log=False关掉冗余日志，现场看着干净。参数上，use_angle_cls=True会多跑一个方向分类模型，对拍歪的标签有用，代价是慢一点，如果图片方向固定可以关掉省时间。
3.2 用 spec 文件精确控制打包过程
直接敲pyinstaller -F main.py大概率失败，因为 PaddleOCR 有大量动态导入和隐式依赖，PyInstaller 静态分析扫不到。正确做法是先生成 spec 再改：
pyinstaller --name ocr_tool --onedir main.py注意这里先用--onedir（目录模式）而不是--onefile。单文件模式启动时要把所有东西解压到临时目录，Paddle 的 dll 加载在这种场景下更容易出问题，而且启动慢。目录模式交付时把整个文件夹压缩给现场，一样方便。生成ocr_tool.spec后，重点改Analysis的hiddenimports和datas：
# ocr_tool.spec 关键片段 from PyInstaller.utils.hooks import collect_all, collect_submodules paddle_datas, paddle_bins, paddle_hidden = collect_all('paddle') ocr_datas, ocr_bins, ocr_hidden = collect_all('paddleocr') shapely_datas, shapely_bins, shapely_hidden = collect_all('shapely') a = Analysis( ['main.py'], pathex=[], binaries=paddle_bins + ocr_bins + shapely_bins, datas=paddle_datas + ocr_datas + shapely_datas, hiddenimports=paddle_hidden + ocr_hidden + shapely_hidden + [ 'pyclipper', 'skimage', 'imgaug', 'scipy', 'lmdb', ], hookspath=[], runtime_hooks=[], excludes=['matplotlib', 'tkinter', 'PyQt5'], noarchive=False, )逻辑说明：collect_all会把包的二进制、数据文件和子模块一次性收全，这是解决 Paddle 打包缺 dll 最省事的办法。hiddenimports里补的几个是 PaddleOCR 运行时动态导入、静态分析抓不到的模块，pyclipper和shapely用于检测框后处理，lmdb在部分版本里会被引用。excludes排除 matplotlib、tkinter 这些用不到的大块头，能砍掉几十 MB。参数上，noarchive=False保持默认即可，改成 True 会牺牲启动速度换体积，不划算。
3.3 打包与首次验证
改完 spec 执行：
pyinstaller ocr_tool.spec --noconfirm产物在dist/ocr_tool/下。把models/目录拷到ocr_tool.exe同级，然后拿一张测试图跑：
cd dist/ocr_tool ocr_tool.exe --img test_label.jpg能打印出文字和置信度就算通了。第一次跑建议在没有 Python 环境的机器上验证，或者至少在一个干净的用户账户下跑，因为开发机上往往有全局的 Python 和 dll，会掩盖缺失依赖的问题。这一步是血泪经验，我见过太多次「我电脑上好好的，客户那边一打开就闪退」。
4. 避坑与排查：打包后最常见的五类翻车
4.1 现象：双击 exe 一闪而过，命令行看报错是ModuleNotFoundError
原因：PyInstaller 静态分析漏掉了动态导入的模块，PaddleOCR 内部大量用importlib和字符串导入，扫不到。解决：在 spec 的hiddenimports里补上缺失模块名，或者干脆用collect_submodules('paddleocr')全量收。定位方法是在命令行里运行 exe，看 traceback 最后一行缺哪个模块，逐个补。别一次补一堆，容易引入新问题。
4.2 现象：报FileNotFoundError找不到ppocr_keys_v1.txt或模型文件
原因：模型和字典没跟着走，或者路径用了相对当前工作目录的写法。PyInstaller 打包后工作目录可能不是 exe 所在目录。解决：统一用get_base_dir()那种基于sys.executable的绝对路径定位，模型外置到 exe 同级。字典文件确认在rec目录下且文件名一致，识别模型和字典必须配套，用错字典会输出乱码。
4.3 现象：启动时报DLL load failed或找不到 msvcp140.dll
原因：Paddle 依赖的 VC++ 运行库在目标机器上缺失，或者打包时漏了某个 dll。解决：一是让现场装一遍 Microsoft Visual C++ Redistributable；二是用collect_all('paddle')确保 dll 被收进去；三是用 Dependency Walker 或dumpbin /dependents查 exe 依赖了哪些 dll，逐个核对。工控机系统版本老的话，这个坑概率很高。
4.4 现象：识别结果为空，但程序不报错
原因：图片路径传错、图片格式 OpenCV 读不了（比如某些 CMYK 的 jpg）、或者检测阈值把框过滤掉了。解决：先在源码环境用同一张图跑，确认模型本身没问题；再检查打包后传入的路径是不是被 shell 转义了。如果是低对比度标签，调det_db_box_thresh和det_db_thresh参数，适当降低阈值。参数在PaddleOCR()初始化时传，比如det_db_box_thresh=0.3。
4.5 现象：exe 体积超过 1GB，或者启动要十几秒
原因：把整个 paddle 包连同测试数据、无用子模块都打进去了，或者用了单文件模式。解决：用excludes排除 matplotlib、tkinter、PyQt、IPython 等；确认用的是--onedir；collect_all虽然省事但会收进一些用不到的东西，体积敏感时可以改成collect_dynamic_libs加手工指定 datas。启动慢主要是单文件解压导致，换目录模式立竿见影。
5. 进阶技巧：体积裁剪、批量识别与一个自检习惯
5.1 把体积从 1GB 压到 400MB 左右
collect_all('paddle')会把 Paddle 的静态库、头文件、测试资源都收进来，实际运行只需要动态库和少量数据。体积敏感时，可以改成只收动态库：
from PyInstaller.utils.hooks import collect_dynamic_libs, collect_data_files paddle_bins = collect_dynamic_libs('paddle') paddle_datas = collect_data_files('paddle', include_py_files=False)collect_dynamic_libs只抓.dll/.so，collect_data_files抓非 Python 的数据文件，include_py_files=False避免把源码再塞一遍。配合excludes排除paddle.distributed、paddle.jit、paddle.fluid（如果版本还用不到）这些大模块，能砍掉不少。裁剪后一定要重新跑一遍识别验证，别为了体积把功能砍没了。
5.2 批量识别与结果落盘
现场往往不是识别一张，而是一个文件夹的图片。入口脚本可以扩展成批量模式，把结果写成 CSV，方便后续导入系统：
import csv import glob def batch_ocr(ocr, img_dir, out_csv): files = glob.glob(os.path.join(img_dir, '*.jpg')) + \ glob.glob(os.path.join(img_dir, '*.png')) with open(out_csv, 'w', newline='', encoding='utf-8-sig') as f: writer = csv.writer(f) writer.writerow(['file', 'text', 'score']) for fp in files: res = ocr.ocr(fp, cls=True) for line in (res[0] or []): _, (text, score) = line writer.writerow([os.path.basename(fp), text, f'{score:.4f}'])encoding='utf-8-sig'是为了 Excel 打开 CSV 不乱码，这个细节现场很受用。批量模式下建议把show_log关掉，否则日志刷屏。如果图片量大，可以考虑把 OCR 对象初始化一次复用，别每张图都重新PaddleOCR()，初始化模型加载很耗时。
5.3 一个我强制自己走的自检流程
打包这类工具，我现在的习惯是：每次改完 spec 或模型，先在开发机跑通，然后把 dist 目录整个拷到一台没装过 Python 的干净 Windows 上，断网，双击运行，拿三张不同类型的图（清晰标签、倾斜标签、低对比度标签）各测一遍，再跑一次批量模式。这个流程走完，交付翻车概率能降到很低。有一次偷懒跳过了干净机器验证，结果客户现场因为缺一个 VC 运行库全员卡住，从那以后我每次打包完都强制走一遍这个自检，再急也不省。希望这套流程能帮到你，少走点我踩过的弯路。
本文还有配套的精品资源，点击获取
