企业官网建设流程全解析

使用 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 环境的终端用户或生产服务器。

一、打包方式选型：为什么选择 PyInstaller

PaddleOCR 官方目前只支持通过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 "paddleocr@git+https://github.com/PaddlePaddle/PaddleOCR.git" # 全部可选能力 # python -m pip install "paddleocr[all]@git+https://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 环境中安装 PyInstaller：

pip 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', required=True, help='Your file name, e.g. main.py.') parser.add_argument('--nvidia', action='store_true', help='Include 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, check=True) except subprocess.CalledProcessError as e: print("Installation failed:", e) sys.exit(1)

3.1 脚本逐段逻辑拆解

• import paddlex与paddlex.utils.deps.BASE_DEP_SPECS：PaddleOCR 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_SPECS（PaddleX 内部维护的"基础依赖清单"，键为包名）可以视为 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 支持的脚本参数

四、执行打包

4.1 调用示例

# 基础打包：仅打包你的入口脚本及 PaddleOCR/Paddle 运行依赖 python package.py --file main.py # 携带 GPU 依赖：将 NVIDIA CUDA、cuDNN 相关依赖库打包至可执行文件的同级目录 python package.py --file main.py --nvidia

4.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目录。

五、打包原理与依赖收集要点

理解打包脚本为何这样写，有助于你排查自定义场景下的问题：

• 动态发现而非静态 import：PaddleOCR 通过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 运行时库。处理方式二选一：

1. 检查目标机器的系统环境变量是否正确包含了 NVIDIA CUDA、cuDNN 相关依赖库路径；
2. 在运行打包脚本时添加--nvidia，将 CUDA、cuDNN 相关依赖库打包进可执行文件的同级目录，随程序一起分发。

七、附录：官方测试环境

官方文档给出上述打包流程的实测环境，可作为版本兼容性参考：

• 操作系统：Win 11
• Python：3.10.18
• PaddlePaddle：3.0.0
• PaddleX：3.1.3
• PaddleOCR：3.1.0
• PyInstaller：6.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