PaddleOCR 3.7 安装教程：真正能跑通的命令

安装命令生成器#

本页的生成器默认使用飞桨官方源（www.paddlepaddle.org.cn）安装 CPU 版 PaddlePaddle，这也是官方安装文档的写法；如果你在海外，可以切换到 PyPI——我们自己测试时用的就是 PyPI 上的 3.2.0。生成器下方的提示说明目前为英文。生成的命令里，首次运行会从 Hugging Face 下载模型；在国内请先按 下文 设置 PADDLE_PDX_MODEL_SOURCE=bos。

各组件之间的关系#

从 PaddleOCR 3.x 开始，paddleocr 包不再自带运行时。它是构建在 PaddleX 之上的一层薄封装（会自动安装，PaddleOCR 3.7 对应 3.7.x 版本），模型运行在你另行安装的推理引擎上：¹³

如果没装引擎，默认产线会在第一次预测时报错："Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed." 这是首次运行最常见的错误——解决办法就是下面的第 2 步。

engine 参数可选 "paddle"、"paddle_static"、"paddle_dynamic"、"transformers" 和 "onnxruntime"。不设置时，PaddleOCR 在大多数情况下使用 PaddlePaddle。一个环境里只装一个引擎：官方文档提醒，不同引擎的依赖可能冲突。³

CPU 安装（Linux、Windows、macOS）#

1. 创建干净的虚拟环境#

   Linux / macOSWindows

   复制

   python3 -m venv .venv
   source .venv/bin/activate
   python -m pip install --upgrade pip

   py -3.12 -m venv .venv
   .venv\Scripts\activate
   python -m pip install --upgrade pip

2. 安装锁定版本的引擎#

   飞桨源（推荐）PyPI

   复制

   python -m pip install paddlepaddle==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

   python -m pip install paddlepaddle==3.2.0

   这是官方安装文档锁定的版本（文档从 paddlepaddle.org.cn 安装；PyPI 也发布了 3.2.0 的 wheel，覆盖 Linux x86-64、Linux ARM64、Windows 和 Apple Silicon 上的 Python 3.9–3.13，我们测试时用的就是 PyPI）。¹²

3. 安装 PaddleOCR#

   $python -m pip install paddleocr==3.7.0复制

   如果不止需要文字识别，可以加上 extra："paddleocr[doc-parser]" 用于 PP-StructureV3 和 PaddleOCR-VL，"paddleocr[all]" 安装全部功能，"paddleocr[doc2md]" 用于把 Word/Excel/PowerPoint 转成 Markdown。

4. 运行#

   $paddleocr ocr -i https://paddle-model-ecology.bj.bcebos.com/paddlex/imgs/demo_image/general_ocr_002.png --save_path ./output复制

   第一次运行会把 PP-OCRv6 medium（在我们的安装中，检测和识别模型合计占用约 139 MB 磁盘空间）下载到 ~/.paddlex/official_models，之后几秒钟就能启动。在国内如果下载很慢或失败，先设置 PADDLE_PDX_MODEL_SOURCE=bos（见 模型下载）。

用 ONNX Runtime 在 CPU 上安装（我们测试中最快）#

PaddleOCR 3.5 新增了 ONNX Runtime 引擎。在我们的 4 vCPU 测试机上，它运行 PP-OCRv6 各档都比 PaddlePaddle 3.2.0 快 1.4–1.5 倍，识别文本完全一致。官方文档只介绍了用于 NVIDIA CUDA 12.x 的 onnxruntime-gpu；CPU 上我们用的是普通的 onnxruntime 包。³⁷

python -m pip install paddleocr==3.7.0 onnxruntime
paddleocr ocr -i receipt.jpg --engine onnxruntime --save_path ./output

from paddleocr import PaddleOCR

ocr = PaddleOCR(engine="onnxruntime")   # 会下载 *_onnx 版本的模型
result = ocr.predict("receipt.jpg")
print(result[0]["rec_texts"])

我们在一个只装了 paddleocr 3.7.0 和 onnxruntime 1.31.1 的全新环境里验证过——完全没有 PaddlePaddle——Python API 和命令行都能正常运行。首次加载时会刷出一串黄色的 [W:onnxruntime ... Removing initializer ...]，这是无害的计算图优化警告，不是错误。

NVIDIA GPU 安装#

PaddlePaddle 3.x 的 GPU 版不在 PyPI 上。PyPI 上最新的 paddlepaddle-gpu 是 2024 年 9 月的 2.6.2，而 PaddleOCR 3.x 需要 PaddlePaddle 3.0 或更高版本。请根据显卡驱动版本从飞桨官方源安装：¹²

只有显卡驱动版本才重要——官方文档明确说明，机器上装的 CUDA Toolkit 版本无关紧要。用 nvidia-smi 查看驱动版本，然后确认 PaddlePaddle 能识别到 GPU：

python -c "import paddle; print(paddle.is_compiled_with_cuda())"   # 必须输出 True
paddleocr ocr -i receipt.jpg --device gpu:0

在 Python 中用 PaddleOCR(device="gpu:0") 指定设备。2.x 的参数 use_gpu=True 已经不存在，会报 ValueError: Unknown argument: use_gpu——见 迁移指南。

macOS（Apple Silicon 与 Intel）#

PyPI 为每个 3.x 版本都提供了 Apple Silicon（macosx_11_0_arm64）的 PaddlePaddle wheel，所以上面的 CPU 命令在 M1–M4 Mac 上无需改动即可使用。macOS 没有 CUDA，device 保持默认即可。官方的 Apple Silicon 版 PaddleOCR-VL 指南称，精度和速度已在 M4 上验证，那里只支持 PaddlePaddle 引擎，且官方 Docker 镜像无法在 Apple Silicon 上运行。²

Intel Mac 则是另一回事：PyPI 上最后一个 x86-64 macOS wheel 是 PaddlePaddle 3.0.0。这个版本满足 PaddleOCR 3.x 文档中的最低要求，但我们没有在 Intel Mac 上测试过。在上面的生成器中选择 macOS（Intel）时，会自动帮你锁定这个版本。

Windows#

• 使用 py 启动器和 venv（见第 1 步），其余命令与 Linux 完全相同。
• RTX 50 系列显卡需要 GPU 表格中提到的专用安装包。
• Windows 不直接支持高性能推理（enable_hpi），官方文档建议改用 Docker 或 WSL。⁵

Docker#

官方镜像托管在百度的镜像仓库。PaddleOCR-VL 有现成可用的镜像（约 8 GB；内置模型的 -offline 版本约 10 GB），需要 Docker 19.03+ 以及支持 CUDA 12.6+ 的 NVIDIA 驱动：⁶

docker run -it --gpus all --network host \
  ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-vl:latest-nvidia-gpu /bin/bash

文字识别和 PP-StructureV3 官方没有提供专门的 PaddleOCR 镜像。用我们测试过的同一组锁定版本，可以这样构建一个最小镜像（这个 Dockerfile 是我们的示例，不是官方提供的）：

FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
 && rm -rf /var/lib/apt/lists/*
RUN python -m pip install --no-cache-dir paddlepaddle==3.2.0 paddleocr==3.7.0
# 可选：把模型打包进镜像，容器启动时无需联网
RUN python -c "from paddleocr import PaddleOCR; PaddleOCR()"

libgl1 这一行可以避免 slim 镜像上经典的 ImportError: libGL.so.1。不要用换成 opencv-python-headless 的方式“修复”这个错误：PaddleX 会按名称检查 opencv-contrib-python，替换后 OCR 产线反而会坏掉。原因。

Google Colab 与 Kaggle#

!pip install paddlepaddle-gpu==3.2.0 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
!pip install "paddleocr[doc-parser]==3.7.0"

!pip install paddlepaddle==3.2.0 "paddleocr==3.7.0"

安装完成后重启运行时，再执行 from paddleocr import PaddleOCR。

支持的 Python 版本#

本站所有内容都是在 Python 3.13 上跑的。如果想用上所有可选功能，Python 3.10–3.12 最稳妥。²⁵

模型下载、缓存与离线使用#

模型在首次使用时下载到 ~/.paddlex/official_models/<model_name>。设置 PADDLE_PDX_CACHE_HOME 可以更改缓存位置。默认下载源是 Hugging Face，在中国大陆可能很慢甚至无法访问；这时把 PADDLE_PDX_MODEL_SOURCE 设为 bos（百度对象存储）、modelscope（魔搭）或 aistudio（飞桨星河社区）即可。⁴

export PADDLE_PDX_MODEL_SOURCE=bos          # Windows：set PADDLE_PDX_MODEL_SOURCE=bos
export PADDLE_PDX_CACHE_HOME=/data/paddlex  # 可选：更改模型缓存目录

对于无法联网的机器，可以从能联网的机器上把模型文件夹复制到相同的缓存路径，或者用 text_detection_model_dir 和 text_recognition_model_dir 让产线直接加载本地文件夹。

还有两个文档里没写、只在源码中能看到的细节：PaddleX 下载前会先检查各模型源能否连通，设置 PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK 可以跳过这一检查——但它是按原始字符串读取的，所以任何非空值，哪怕是 0 或 false，都会关闭检查。⁴

验证安装#

python -c "import paddleocr; print(paddleocr.__version__)"   # 3.7.0
python -c "import paddle; print(paddle.__version__)"         # 3.2.0
python -c "import paddle; paddle.utils.run_check()"           # "PaddlePaddle is installed successfully!"

从 PaddleOCR 2.x 升级#

3.x 不向后兼容：ocr(img, cls=True)、use_gpu、use_angle_cls、draw_ocr 和 PPStructure 都已移除或改名。把旧代码粘贴到我们的 2.x → 3.x 代码转换工具，就能看到具体要改哪些地方。如果暂时必须继续用 2.x，请锁定版本：pip install "paddleocr<3"。

安装常见问题#