使用 PyInstaller 打包 PaddleOCR 项目：从环境准备到可执行程序发布

使用 PyInstaller 打包 PaddleOCR 项目从环境准备到可执行程序发布【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR本指南以 PaddleOCR 官方文档 packaging.en.md对应中文版 packaging.md为核心系统讲解如何将基于 PaddleOCR 的 Python 项目打包为独立可执行程序。你将掌握打包前的环境准备与依赖核查方法、官方推荐的 PyInstaller 打包脚本及其参数用法、打包产物的验证方式以及 CUDA/cuDNN 依赖缺失等高频问题的排查思路可直接应用于把 OCR 工具交付给无 Python 环境的终端用户或生产服务器。一、打包方式选型为什么选择 PyInstallerPaddleOCR 官方目前只支持通过PyInstaller对项目进行打包。官方文档明确指出由于Nuitka 的打包原理与 PaddleOCR 不适配当前暂不支持通过 Nuitka 打包。原因并不难理解PaddleOCR 的推理链路依赖 PaddlePaddle/PaddleX 动态加载模型、插件与运行时动态库如paddle的共享库、NVIDIA CUDA/cuDNN 动态链接库等这类运行时按需发现资源的模式与 PyInstaller 的静态收集冻结模型配合更成熟。因此本文所有方案均围绕 PyInstaller 展开。二、准备环境打包前需要完成两件事安装 PaddleOCR 本体、安装 PyInstaller。2.1 安装 PaddleOCR按照 PaddleOCR 安装文档中文版见 installation.md完成 PaddleOCR 的安装。安装方式有两种# 方式一从 PyPI 安装仅通用 OCR 与文档图像预处理能力 python -m pip install paddleocr # 方式二安装全部可选能力文档解析、文档理解、文档翻译、关键信息抽取等 # python -m pip install paddleocr[all]也可以从源码安装以跟随仓库当前默认分支# 默认能力 python -m pip install paddleocrgithttps://github.com/PaddlePaddle/PaddleOCR.git # 全部可选能力 # python -m pip install paddleocr[all]githttps://github.com/PaddlePaddle/PaddleOCR.git注意PaddleOCR 3.x 的 Python 包本身要求 Python 3.8 及以上doc-parser、ie、trans、all等可选依赖组因上游依赖要求 Python 3.9 及以上。若你的待打包脚本涉及文档解析、信息抽取或翻译能力请确保使用 Python 3.9 环境。2.2 安装 PyInstaller在同一个 Python 环境中安装 PyInstallerpip install pyinstaller依赖核查是打包前最关键的一步请确认当前准备环境中已经安装了待打包 Python 脚本所需的全部依赖。PyInstaller 只会收集它看得到的包如果脚本运行依赖的库在当前环境中缺失打包后的可执行程序运行时就可能因缺少依赖而异常。官方打包脚本中通过--copy-metadata动态补充元信息的机制见下文第三节正是建立在当前环境依赖完整这一前提之上的。三、官方打包脚本详解将下面的 Python 脚本拷贝保存为一个py文件官方建议命名为package.py它本质上是一个 PyInstaller 命令行生成器先分析当前环境中已安装的 PaddleOCR 相关依赖再动态拼装出一条完整的pyinstaller命令并执行。import paddlex import importlib.metadata import argparse import subprocess import sys parser argparse.ArgumentParser() parser.add_argument(--file, requiredTrue, helpYour file name, e.g. main.py.) parser.add_argument(--nvidia, actionstore_true, helpInclude NVIDIA CUDA and cuDNN dependencies.) args parser.parse_args() main_file args.file user_deps [dist.metadata[Name] for dist in importlib.metadata.distributions()] deps_all list(paddlex.utils.deps.BASE_DEP_SPECS.keys()) deps_need [dep for dep in user_deps if dep in deps_all] cmd [ pyinstaller, main_file, --collect-data, paddlex, --collect-binaries, paddle ] if args.nvidia: cmd [--collect-binaries, nvidia] for dep in deps_need: cmd [--copy-metadata, dep] print(PyInstaller command:, .join(cmd)) try: result subprocess.run(cmd, checkTrue) except subprocess.CalledProcessError as e: print(Installation failed:, e) sys.exit(1)3.1 脚本逐段逻辑拆解import paddlex与paddlex.utils.deps.BASE_DEP_SPECSPaddleOCR 3.x 的运行内核由 PaddleX 提供。从 pyproject.toml 可以看到paddleocr基础依赖即包含paddlex[ocr-core]3.7.0,3.8.0而doc-parser、ie、trans、all等能力组也都基于paddlex的相应 extras。因此paddlex.utils.deps.BASE_DEP_SPECSPaddleX 内部维护的基础依赖清单键为包名可以视为 PaddleOCR 所需依赖的权威来源。依赖交集计算user_deps枚举当前环境中所有已安装发行包通过importlib.metadata.distributions()deps_need取其与BASE_DEP_SPECS的交集即当前环境里实际装了的、PaddleOCR 又需要的依赖子集。这样既不会漏掉已安装的能力组依赖也不会盲目为不存在的包生成参数。命令拼装核心参数固定为--collect-data paddlex与--collect-binaries paddle--collect-data paddlex收集 PaddleX 包内的数据文件模型配置文件、资源文件等这些非 Python 数据是推理时动态读取的PyInstaller 默认不会跟随 import 自动收集--collect-binaries paddle收集 Paddle 框架的二进制动态库避免打包后出现libpaddle等共享库缺失可选--collect-binaries nvidia收集 NVIDIA CUDA/cuDNN 动态链接库见 3.2 节每个deps_need中的依赖追加一个--copy-metadata dep把该发行包的元信息如METADATA文件一并打包以支持运行时对依赖版本信息的查询——PaddleX/PaddleOCR 启动时会校验依赖完整性缺少元信息正是xxx requires additional dependencies报错的常见来源。3.2 支持的脚本参数参数是否必需说明--file是待打包的文件名如main.py即你的入口脚本--nvidia否将 NVIDIA 的 CUDA、cuDNN 相关依赖库一同打包到可执行文件的同级目录。如果系统环境变量路径已包含 CUDA/cuDNN 依赖库或你的应用不需要 CUDA/cuDNN如纯 CPU 推理则无需开启四、执行打包4.1 调用示例# 基础打包仅打包你的入口脚本及 PaddleOCR/Paddle 运行依赖 python package.py --file main.py # 携带 GPU 依赖将 NVIDIA CUDA、cuDNN 相关依赖库打包至可执行文件的同级目录 python package.py --file main.py --nvidia4.2 运行结果脚本会打印最终生成的 PyInstaller 命令并执行形如pyinstaller main.py --collect-data paddlex --collect-binaries paddle [--copy-metadata xxx ...]其中--copy-metadata xxx会根据当前环境已安装的 PaddleOCR 所需依赖动态添加包的元信息。打包完成后可执行文件和相关依赖库将生成在dist文件夹中。dist目录即最终的交付物在 Windows 下包含.exe及同级的 DLL/数据资源在 Linux/macOS 下包含可执行二进制及同级依赖文件。将该目录整体拷贝到目标机器即可运行目标机器无需再安装 Python 与 Paddle 环境。提示PyInstaller 还会生成build目录中间产物与xxx.spec文件构建配置如需重新打包可基于 spec 文件定制日常交付可忽略build目录。五、打包原理与依赖收集要点理解打包脚本为何这样写有助于你排查自定义场景下的问题动态发现而非静态 importPaddleOCR 通过create_paddleocr系列工厂方法按需加载模型与后端相关入口见 paddleocr/init.py且支持paddleocr命令行工具见 paddleocr/main.py 与 paddleocr/_cli.py。运行时才执行 import 的模块PyInstaller 的分析器无法静态追踪这正是需要显式--collect-*收集数据与二进制的原因。元信息即运行时契约PaddleX 在初始化时会校验依赖版本RuntimeError: xxx requires additional dependencies即由此触发。--copy-metadata确保打包环境中保留了这些校验所需的信息。GPU 依赖的两种供给方式要么依赖目标机器系统环境变量中已有的 CUDA/cuDNN 路径要么通过--nvidia让 PyInstaller 把 NVIDIA 相关动态库收集进可执行文件同级目录实现自带运行时。二者选其一即可详见第六节。六、常见问题排查问题 1运行可执行文件时报错RuntimeError: xxx requires additional dependencies说明当前打包环境缺少相关依赖PaddleX 运行时的依赖校验未通过。请回到准备环境一节确认已按 PaddleOCR 安装文档 正确安装 PaddleOCR 及其所需能力组如文档解析对应doc-parser、信息抽取对应ie、翻译对应trans、全功能对应all并在同一环境中重新打包。问题 2报错提示找不到 CUDA 或 cuDNN 相关动态链接库说明可执行程序运行时无法定位 NVIDIA 运行时库。处理方式二选一检查目标机器的系统环境变量是否正确包含了 NVIDIA CUDA、cuDNN 相关依赖库路径在运行打包脚本时添加--nvidia将 CUDA、cuDNN 相关依赖库打包进可执行文件的同级目录随程序一起分发。七、附录官方测试环境官方文档给出上述打包流程的实测环境可作为版本兼容性参考操作系统Win 11Python3.10.18PaddlePaddle3.0.0PaddleX3.1.3PaddleOCR3.1.0PyInstaller6.14.2如果你的环境版本与之差异较大尤其 PaddleOCR/PaddleX 升级后建议在打包后于干净的目标机器上做一次冒烟验证至少运行一次完整的 OCR 推理确认依赖收集完整后再行分发。八、小结将 PaddleOCR 项目打包为可执行程序核心链路是完整安装 PaddleOCR 与 PyInstaller → 运行官方package.py脚本自动拼装pyinstaller命令 → 通过--collect-data/--collect-binaries/--copy-metadata收集数据、二进制与元信息 → 从dist目录分发产物。对于 GPU 场景按需开启--nvidia将 CUDA/cuDNN 一并打包即可。遇到依赖报错时优先回到环境准备环节核查依赖完整性再检查 CUDA/cuDNN 路径供给方式即可覆盖绝大多数打包问题。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考