PaddleOCR 3.x 完整安装指南：Python 包、可选依赖组、推理引擎与训练环境-酒店常州论坛

PaddleOCR 3.x 完整安装指南：Python 包、可选依赖组、推理引擎与训练环境

【免费下载链接】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 仓库中 docs/version3.x/installation.en.md 为骨架，系统讲解 PaddleOCR 3.x 的两大独立安装维度：其一为面向本地推理的paddleocrPython 分发包与按能力域拆分的可选依赖组（doc-parser、ie、trans、doc2md、all），以及按需安装的推理引擎；其二为面向模型训练与导出的飞桨框架与训练依赖。读完本文，你将能够根据"仅做通用 OCR 推理"、"需要文档解析 / 关键信息抽取 / 文档翻译 / 文档转 Markdown"、"需要本地训练与导出模型"等不同诉求，选择最小化且正确的安装组合，并理解 PaddleOCR 3.5 统一推理引擎配置（engine/engine_config）背后的安装与选型逻辑。

1. 安装前需要理解的两个独立维度

PaddleOCR 3.x 将"运行预训练产线做推理"与"训练 / 导出模型"拆分为两条互不干扰的安装路径：

推理路径（第 1 节）：安装paddleocr分发包、按能力域选择可选依赖组、再按需安装推理引擎。适用于在本地调用预训练产线完成推理，以及文档格式转换等辅助功能。
训练 / 导出路径（第 2 节）：单独安装飞桨框架与训练相关依赖。适用于模型训练与模型导出。

两条路径可以在同一环境中共存，无需强制隔离。原文档明确指出：模型训练与模型导出与上述推理安装路径相互独立。

从源码看，这一设计直接体现在 pyproject.toml 中：paddleocr项目的基础依赖（dependencies）只声明了paddlex[ocr-core]>=3.7.0,<3.8.0、PyYAML、requests、aiohttp、typing-extensions等运行时必需的最小集合，而训练依赖（shapely、scikit-image、pyclipper、lmdb、albumentations等）则独立维护在仓库根目录的 requirements.txt 中，只有走训练路径才需要安装。

Python 版本要求速查

| 安装对象 | 最低 Python 版本 | 原因 | | - | - | - | |paddleocr本体 | 3.8 | 项目自身支持 | |doc2md依赖组 | 3.8 | 上游依赖兼容 | |doc-parser/ie/trans/all依赖组 | 3.9 | 受上游依赖限制 | | 训练与模型导出 | 3.8 | 文档明确声明 |

这一点同样可以在 pyproject.toml 的 classifiers 中印证：项目声明支持 Python 3.8 ~ 3.13。

2. 安装`paddleocr`：默认能力与全量能力

2.1 从 PyPI 安装

# 默认能力：仅通用 OCR 与文档图像预处理 python -m pip install paddleocr # 全量可选能力：文档解析、文档理解、文档翻译、关键信息抽取等 # python -m pip install "paddleocr[all]"

默认安装只包含通用 OCR 与文档图像预处理所需的运行时依赖，不会把全部 PaddleX 依赖一并带入。依据 paddleocr_and_paddlex.en.md 的说明，得益于 PaddleX 的可选依赖安装机制，安装paddleocr分发包并不会包含 PaddleX 的全部依赖，只会安装 OCR 相关任务所需的那些，用户无需担心依赖体积过度膨胀。

2.2 从源码安装

# 默认能力，默认跟踪仓库当前默认分支 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命令行入口由 pyproject.toml 中的[project.scripts]声明（paddleocr = "paddleocr.__main__:console_entry"），实际入口实现位于 paddleocr/main.py，所有子命令（ocr、text_detection、PP-StructureV3、PP-ChatOCRv4-doc等）在 paddleocr/_cli.py 中统一注册。

3. 按能力域选择可选依赖组

除all之外，PaddleOCR 提供按能力域拆分的可选依赖组，实现"按需安装、最小化依赖"。各依赖组与功能的对应关系如下：

依赖组的底层实现在 pyproject.toml 的[project.optional-dependencies]中有精确映射：

doc-parser=paddlex[ocr,genai-client]>=3.7.0,<3.8.0
ie=paddlex[ie]>=3.7.0,<3.8.0
trans=paddlex[trans]>=3.7.0,<3.8.0
doc2md=python-docx>=0.8.11+python-pptx>=0.6.21+openpyxl>=3.0.0+pylatexenc>=2.10,<3
all=paddlex[ocr,genai-client,ie,trans]>=3.7.0,<3.8.0+ doc2md 的四个包

从这份声明可以看到一个关键事实：doc2md依赖组不依赖 PaddleX，仅由python-docx、python-pptx、openpyxl、pylatexenc组成，这正是它能在 Python 3.8 上工作的原因；而doc-parser、ie、trans等组通过 PaddleX 的可选 extra 引入对应能力，受上游依赖限制需要 Python 3.9+。

依赖组选择建议

通用 OCR 产线与文档图像预处理产线无需任何额外依赖组；
需要文档解析、信息抽取、文档翻译等能力时，按上表安装对应组；
各产线所属依赖组见对应产线文档（如 PP-StructureV3、PP-ChatOCRv4、PP-DocTranslation、doc2md）；
对于单个功能模块，安装任一包含该模块的依赖组后即可调用其基础能力。

4. 安装推理引擎（按需）

PaddleOCR 3.5 采用统一推理引擎配置机制：通过engine选择底层推理引擎，通过engine_config传入引擎专属设置。这一机制同时适用于单个模型和产线。若未显式指定engine，默认行为与旧版本保持一致——除高性能推理、生成式 AI 客户端请求等少数场景外，PaddleOCR 绝大多数情况下使用飞桨框架执行推理；若显式指定了engine，则初始化时优先遵循所选引擎。

详细的安装与配置说明见推理引擎与配置说明，各引擎安装要点如下：

⚠️ 不同推理引擎之间可能存在依赖冲突，建议每个环境只安装一种推理引擎。

引擎选型要点：

paddle：飞桨框架统一入口，按模型类型与模型目录中的文件自动选择paddle_static或paddle_dynamic，两者同时可用时优先静态图；
paddle_static：静态图推理，适合追求更优推理性能或更细粒度性能调优的场景；
paddle_dynamic：动态图推理，比静态图更灵活、更易调试；
transformers：Hugging Face Transformers 推理，便于融入 HF 生态；
onnxruntime：ONNX Runtime 推理，用于加载和执行 ONNX 格式模型。

5. 训练与导出路径：飞桨框架 + 训练依赖

5.1 安装飞桨框架

若要进行模型训练或模型导出，需要先安装飞桨框架，详细步骤见飞桨框架安装文档。其 pip 安装要点：

# CPU 版本 python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ # GPU 版本，要求驱动 >= 450.80.02 (Linux) 或 >= 452.39 (Windows) python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu118/ # GPU 版本，要求驱动 >= 550.54.14 python -m pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/

安装成功后验证：

python -c "import paddle; print(paddle.__version__)"

文档特别提醒：无需关注物理机 CUDA 版本，只需关注 GPU 驱动版本。另外，如果当前环境中已安装飞桨之外的推理引擎（如 Transformers），可能出现依赖冲突，建议在全新环境中安装。

关于 PaddleOCR 与 PaddlePaddle、PaddleX 的版本对应关系，可参考 PaddleOCR 与 PaddleX 中的版本对照表：例如 PaddleOCR3.5.x对应 PaddleX>= 3.5.0, < 3.6.0、PaddlePaddle>= 3.0.0；当前 pyproject.toml 声明paddlex[ocr-core]>=3.7.0,<3.8.0，即对应 PaddleOCR3.7.x。

5.2 克隆仓库并安装训练依赖

# 推荐方式 git clone https://github.com/PaddlePaddle/PaddleOCR # （可选）切换到指定分支 git checkout release/3.5 # 如果因网络问题克隆失败，也可使用码云仓库： git clone https://gitee.com/paddlepaddle/PaddleOCR # 注：码云托管代码可能无法实时同步，存在 3~5 天延时，请优先使用推荐方式。

克隆完成后安装其余训练依赖：

python -m pip install -r requirements.txt

requirements.txt 中声明的训练依赖包括：shapely、scikit-image、pyclipper、lmdb（按 Python 版本区分版本约束：Python >= 3.9 装最新版，< 3.9 装lmdb<1.5）、tqdm、numpy、rapidfuzz、opencv-python、opencv-contrib-python、cython、Pillow、pyyaml、requests、albumentations、albucore、packaging等，覆盖了数据加载（LMDB 数据集）、图像增强（albumentations）、后处理几何计算（shapely / pyclipper）、可视化与日志等训练全链路所需组件。

6. 安装完成后的快速验证

安装完成后，可以通过 PaddleOCR 命令行快速验证环境是否可用。以通用 OCR 产线为例（paddleocr ocr），也可以在模型子命令中直接指定推理引擎：

# 使用飞桨静态图引擎执行通用 OCR paddleocr ocr -i general_ocr_001.png --engine paddle_static # 单个模型使用 Transformers 引擎 paddleocr text_detection -i general_ocr_001.png --engine transformers # 单个模型使用 ONNX Runtime 引擎 paddleocr text_detection -i general_ocr_001.png --engine onnxruntime

在 Python API 中，推理引擎的指定方式同样直观：

from paddleocr import TextDetection model = TextDetection( model_name="PP-OCRv5_server_det", engine="paddle_static", engine_config={ "device_type": "cpu", "cpu_threads": 4, "run_mode": "mkldnn", }, ) result = model.predict("general_ocr_001.png")

产线级的快速使用示例可进一步参考 quick_start.en.md。

7. 常见问题与注意事项

两条安装维度互不冲突：paddleocr包 + 可选依赖组（推理路径）与飞桨框架 +requirements.txt（训练路径）可在同一环境共存，无需强制隔离。
依赖冲突优先"干净环境"：若环境已装 Transformers 等其他推理引擎，再安装飞桨框架可能出现依赖冲突，建议使用全新虚拟环境。
推理引擎一环境一个：不同推理引擎（飞桨 / Transformers / ONNX Runtime）依赖可能冲突，每个环境只装一种。
engine_config的两种形态：同一层级上engine_config可以是"扁平式"（键直接为解析后引擎所需字段，如run_mode、cpu_threads）或"分桶式"（顶层键仅为引擎注册名如paddle_static、transformers，各自映射到嵌套字典），禁止在同一层级混用两种键。
优先级规则：产线通过 CLI 参数或 Python API 初始化参数传入的engine/engine_config优先于产线配置文件中的同名项；配置文件中的全局设置可被子模块覆盖。
版本对应关系：安装前建议核对 PaddleOCR 与 PaddleX 版本对照表，确保paddleocr、PaddleX 与飞桨框架的版本区间匹配，避免因版本错配导致 API 或依赖异常。

8. 相关资源

安装文档（英文原文） / 安装文档（中文版）
推理引擎与配置说明
飞桨框架安装
PaddleOCR 与 PaddleX 的关系与协作
doc2md 文档转 Markdown 说明
pyproject.toml（依赖组声明）
requirements.txt（训练依赖）

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析