企业官网建设流程全解析

使用 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 环境的终端用户。

一、方案总览：为什么选择 PyInstaller

PaddleOCR 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 安装 PyInstaller

pip 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', 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 脚本工作原理拆解

3.2 打包脚本支持的参数

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 需要的依赖动态添加包的元信息——这正是脚本第 43～45 行动态计算的结果，打包命令会先在控制台打印（print("PyInstaller command:", ...)），便于核对。

打包完成后：

• 可执行文件和相关依赖库将生成到dist文件夹中；
• build文件夹为 PyInstaller 的中间产物，可忽略；
• 若开启了--nvidia，CUDA、cuDNN 相关动态链接库会出现在可执行文件的同级目录，而不是依赖系统全局环境变量。

五、附录

5.1 官方测试环境

以上打包流程在如下环境中测试（官方文档附录原文）：

• 操作系统：Win 11
• Python：3.10.18
• PaddlePaddle：3.0.0
• PaddleX：3.1.3
• PaddleOCR：3.1.0
• PyInstaller：6.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(pipeline="OCR") result = ocr.predict(input="demo.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