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

使用 PyInstaller 打包 PaddleOCR 项目从环境准备到可执行文件发布【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR本篇技术指南以 PaddleOCR 官方部署文档 打包PaddleOCR项目 为核心完整讲解如何基于 PyInstaller 将 PaddleOCR 应用如 OCR 产线、单功能模块调用脚本打包为可直接分发的可执行文件。读者阅读并实践本文后将掌握环境准备、打包脚本编写、动态依赖元信息收集、CUDA/cuDNN 依赖打包等关键能力能够把基于 PaddleOCR 的推理程序交付给无 Python 环境的终端用户。一、方案总览为什么选择 PyInstallerPaddleOCR 3.x 的应用层paddleocr包在推理时依赖 PaddleX 产线体系——从 PaddleX 产线封装基类 可以看到OCR 产线类PaddleXPipelineWrapper负责创建底层 PaddleX 产线实例。这意味着一个可运行的 PaddleOCR 程序除了 Python 解释器外还包含PaddleX / PaddleOCR 自身的 Python 包与内置资源文件产线配置、模型清单、静态字典等PaddlePaddle 推理框架及其动态链接库可选NVIDIA CUDA、cuDNN 运行时库程序运行期动态感知到的各类第三方依赖如 opencv、numpy、transformers 等。PyInstaller 通过收集数据文件、收集二进制库、复制包元信息三件事把上述内容整合进一个可执行文件或 dist 目录下的可执行文件 依赖库集合从而让程序脱离原始 Python 环境独立运行。官方文档明确指出由于 Nuitka 的打包原理与 PaddleOCR 不适配当前暂不支持通过 Nuitka 进行打包因此 PyInstaller 是当前推荐的打包路线。二、准备环境2.1 安装 PaddleOCR在打包之前请先根据 PaddleOCR 安装文档 完成 PaddleOCR 的安装。官方文档同时提示请确认当前准备环境中安装有待打包的 Python 脚本所需的全部依赖以避免缺少依赖导致打包后的可执行程序出现异常。这是因为 PyInstaller 打包的是当前环境可见的依赖——脚本 import 了但环境中未安装的库无法被收集进产物。建议在一个干净的虚拟环境中安装 PaddleOCR 及其全部运行依赖后再打包从 依赖组划分 可知若你的脚本用到了文档解析、信息抽取、翻译等能力应安装对应的可选依赖组如doc-parser、ie、trans、all确保环境与脚本需求一致。2.2 安装 PyInstallerpip install pyinstaller官方文档给出其测试环境为 PyInstaller6.14.2建议使用同版本或更新的稳定版本详见文末附录。三、打包脚本全量代码与逐段解析将下方 Python 脚本拷贝后存成py文件文件名可以为package.py。该脚本是官方文档提供的标准打包入口它会根据当前环境已安装的包动态组装 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 模块PaddleOCR 3.x 的产线由 PaddleX 支撑见 产线封装基类打包脚本需要读取其依赖清单importlib.metadata.distributions()枚举当前环境所有已安装发行版返回每个发行版的元数据对象取其Name作为依赖名paddlex.utils.deps.BASE_DEP_SPECS获取 PaddleX 基础依赖规格表该字典的键即 PaddleX 产线运行时必需的依赖包名交集运算deps_need求已安装依赖 ∩ PaddleX 基础依赖只对当前环境真正安装了的 PaddleX 依赖做元数据收集避免对未安装包报错--collect-data paddlex收集 PaddleX 包内的数据文件产线 YAML 配置、模型清单等资源以非 .py 文件形式随包分发PyInstaller 默认不收集需显式指定--collect-binaries paddle收集 PaddlePaddle 的动态链接库飞桨框架的 .so/.dll 运行库依赖此参数进入产物--collect-binaries nvidia可选收集 NVIDIA 运行库将 CUDA、cuDNN 相关依赖库打包到可执行文件的同级目录--copy-metadata dep复制指定包的元数据解决部分库在运行时通过importlib.metadata查询自身版本/入口点而失败的问题3.2 打包脚本支持的参数参数是否必需说明--file是你的待打包文件名如main.py。--nvidia否将 NVIDIA 的 CUDA、cuDNN 相关依赖库一同打包到可执行文件的同级目录中。如果系统环境变量路径已包含 CUDA、cuDNN 相关依赖库或者不需要使用 CUDA、cuDNN 相关依赖库则无需开启。3.3 打包脚本调用示例python package.py --file main.py # 将NVIDIA的CUDA、cuDNN相关依赖库打包至可执行文件的同级目录中。 python package.py --file main.py --nvidia四、运行结果与产物说明执行打包脚本后实际会运行类似如下 PyInstaller 命令pyinstaller main.py --collect-data paddlex --collect-binaries paddle [--copy-metadata xxx …]其中--copy-metadata xxx会根据当前环境已安装的 PaddleOCR 需要的依赖动态添加包的元信息——这正是脚本第 4345 行动态计算的结果打包命令会先在控制台打印print(PyInstaller command:, ...)便于核对。打包完成后可执行文件和相关依赖库将生成到dist文件夹中build文件夹为 PyInstaller 的中间产物可忽略若开启了--nvidiaCUDA、cuDNN 相关动态链接库会出现在可执行文件的同级目录而不是依赖系统全局环境变量。五、附录5.1 官方测试环境以上打包流程在如下环境中测试官方文档附录原文操作系统Win 11Python3.10.18PaddlePaddle3.0.0PaddleX3.1.3PaddleOCR3.1.0PyInstaller6.14.2需要说明的是PaddleOCR 安装文档installation.md要求 Python 3.8 及以上部分可选依赖组要求 3.9因此在该版本区间内的较新 Python 环境理论上均可尝试但若切换环境建议以实际打包与运行验证为准。5.2 常见问题RuntimeError: xxx requires additional dependencies说明当前打包环境缺少相关依赖。请确认已按照准备环境部分的说明正确安装环境——重点检查待打包脚本 import 的每个库是否都已安装以及 PaddleOCR 所需的可选依赖组是否齐全。提示 CUDA、cuDNN 相关动态链接库找不到请检查系统环境变量中是否正确添加 NVIDIA 的 CUDA、cuDNN 相关依赖库路径或者考虑在运行打包脚本时添加--nvidia将 CUDA、cuDNN 相关依赖库打包进可执行文件的同级目录中使产物自包含。六、从文档到实践一份可参考的待打包脚本示例为了让打包什么更具体这里给出一个典型的 PaddleOCR 产线调用脚本骨架对应--file main.py中的main.py其 API 用法可参考 产线使用文档 与 CLI 入口实现 中注册的产线清单from paddleocr import PaddleOCR ocr PaddleOCR(pipelineOCR) result ocr.predict(inputdemo.png) for res in result: print(res)将上述文件与package.py放在同一目录执行python package.py --file main.py即可在dist/下得到可独立分发的可执行程序若目标机器没有预装 CUDA/cuDNN 环境改用python package.py --file main.py --nvidia让产物自带 NVIDIA 运行库。分发前建议在全新、无 Python 环境的机器上做一次冒烟测试重点验证模型权重下载路径、配置文件定位与动态库加载三项是否正常这是 PyInstaller 打包 PaddleOCR 类应用最常见的三类坑点。【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100 languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考