1. 为什么我建议你从源码编译而不是直接pip安装
PaddleOCR 这个工具在中文 OCR 圈子里基本属于绕不开的存在，轻量、模型丰富、对中文场景的适配做得相当到位。但很多人第一次上手就卡在安装这一步——pip 一行命令装完，跑 demo 直接报错，然后开始怀疑人生。我自己前前后后在不同机器上装过不下十次，从 Windows 到 Linux，从 CPU 到 GPU，踩过的坑足够写一篇避雷指南。
先说一个反直觉的结论：如果你只是想在本地快速跑通一个识别 demo，pip 安装确实够用；但只要你打算长期用、要改代码、要换模型、要部署到服务器，源码编译安装才是正路。原因很简单，pip 装的是打包好的 wheel，里面绑定的依赖版本是固定的，一旦你的环境里已经有其他版本的 numpy、opencv 或者 paddlepaddle，冲突几乎是必然的。而源码安装可以让你清楚地看到每个依赖的版本要求，出问题也能定位到具体环节。
这篇文章我会把 PaddleOCR 的安装测试完整走一遍，包括环境准备、依赖选择、安装方式对比、验证脚本、常见报错排查，以及我自己总结的一套"装完必测"的检查清单。不管你是刚接触 OCR 的新手，还是已经用过其他 OCR 工具想迁移过来的老手，应该都能从里面找到有用的东西。
1.1 先搞清楚 PaddleOCR 到底依赖哪些东西
很多人安装失败的根本原因，是没弄明白 PaddleOCR 的依赖分层。它不是一个大包把所有东西都塞进去，而是分成了好几层：
- 底层推理框架：PaddlePaddle（飞桨），这是核心，所有模型推理都靠它。CPU 版和 GPU 版是两个不同的包，装错了直接跑不起来。
- OCR 算法层：PaddleOCR 本身，包含检测、识别、方向分类三个模块的模型和推理逻辑。
- 图像处理依赖：opencv-python、Pillow、numpy 这些，负责图片的读取、预处理和后处理。
- 可选依赖：比如 layoutparser（版面分析）、pyclipper（文本框处理）、shapely（多边形计算）等，不装也能跑基础功能，但某些高级功能会报错。
这里最关键的是PaddlePaddle 和 PaddleOCR 的版本对应关系。我见过太多人装了最新版的 PaddlePaddle，然后装了个老版本的 PaddleOCR，结果 import 就报错。正确的做法是先确定你要用哪个版本的 PaddleOCR，然后去查它要求的 PaddlePaddle 版本范围。
提示：PaddleOCR 的官方文档里有一张版本对应表，安装前务必先看一眼。不要凭感觉装"最新版"，最新版之间不一定兼容。
1.2 CPU 版和 GPU 版的选择逻辑
这个问题我被问过无数次。简单说：
- CPU 版：安装简单，不需要 CUDA 和 cuDNN，适合学习、测试、轻量级应用。缺点是推理速度慢，尤其是检测模型，一张图可能要好几秒。
- GPU 版：需要匹配的 CUDA 和 cuDNN，安装麻烦，但速度快十倍以上，适合生产环境和批量处理。
我的建议是：如果你只是学习或者做 demo，先用 CPU 版跑通流程，确认代码逻辑没问题了，再考虑换 GPU 版。不要一上来就折腾 GPU 环境，CUDA 版本、驱动版本、cuDNN 版本三者之间的匹配关系能把人逼疯。而且很多时候你以为是 PaddleOCR 的问题，其实是 CUDA 环境没配好。
另外提醒一点，GPU 版的 PaddlePaddle 对显卡驱动有最低版本要求，装之前先用nvidia-smi看一下驱动版本，再去查对应的 CUDA 版本。这个顺序不能反。
2. 手把手走一遍完整安装流程
下面这套流程是我在 Linux 环境下反复验证过的，Windows 下大同小异，差异我会单独标注。假设你用的是 Python 3.8 到 3.10 之间的版本，太老或太新的 Python 版本可能会有兼容性问题。
2.1 创建独立的虚拟环境
这一步千万别省。我见过太多人直接在系统 Python 里装，结果把系统环境搞崩了，其他项目也跟着遭殃。用 conda 或者 venv 都行，我个人习惯用 conda，因为管理多版本 Python 更方便。
conda create -n paddleocr python=3.9 conda activate paddleocr如果你不想装 conda，用 venv 也可以：
python -m venv paddleocr_env source paddleocr_env/bin/activate # Linux/Mac # paddleocr_env\Scripts\activate # Windows创建完环境后，先升级一下 pip，避免因为 pip 版本太老导致某些包装不上：
python -m pip install --upgrade pip2.2 安装 PaddlePaddle
这是整个流程里最容易出问题的一步。CPU 版相对简单：
python -m pip install paddlepaddle==2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple注意我指定了版本号 2.5.2，这是为了和后面要装的 PaddleOCR 版本匹配。如果你不指定版本，pip 会装最新的，可能和 PaddleOCR 不兼容。
GPU 版就复杂一些，需要先确认 CUDA 版本。假设你的环境是 CUDA 11.2：
python -m pip install paddlepaddle-gpu==2.5.2.post112 -f https://www.paddlepaddle.org.cn/whl/linux/mkl/avx/stable.html这里的post112就代表 CUDA 11.2。不同 CUDA 版本对应的后缀不一样，装之前一定要去官网查清楚。
装完之后验证一下：
import paddle paddle.utils.run_check()如果输出里出现 "PaddlePaddle is installed successfully"，说明底层框架没问题。如果报错，先别急着装 PaddleOCR，把 PaddlePaddle 的问题解决了再说。
2.3 安装 PaddleOCR
有两种方式，pip 和源码。先说你什么时候用 pip：
python -m pip install paddleocr==2.7.0.3 -i https://pypi.tuna.tsinghua.edu.cn/simple这个方式适合快速验证，但如前所述，依赖冲突的风险较高。如果你要改代码或者长期使用，建议源码安装：
git clone https://github.com/PaddlePaddle/PaddleOCR.git cd PaddleOCR git checkout release/2.7 # 切换到稳定分支 python -m pip install -r requirements.txt python -m pip install -e .-e参数是"可编辑安装"，意思是你在源码目录里改代码，直接生效，不用重新安装。这对调试非常有用。
源码安装时，requirements.txt里列了一堆依赖，其中有些是可选的。如果你只需要基础 OCR 功能，可以手动精简一下，只装核心的几个：
python -m pip install opencv-python pillow numpy pyclipper shapely imgaug pyyaml python-docx这样装出来的环境更干净，出问题的概率也更低。
2.4 下载推理模型
PaddleOCR 的模型不是打包在代码里的，需要单独下载。第一次运行的时候会自动下载，但国内网络环境下自动下载经常失败。我的做法是手动下载好放到指定目录。
模型分三类：检测模型、识别模型、方向分类模型。基础中文场景用这几个就够了：
- 检测模型：
ch_PP-OCRv4_det_infer - 识别模型：
ch_PP-OCRv4_rec_infer - 方向分类模型：
ch_ppocr_mobile_v2.0_cls_infer
下载地址在 PaddleOCR 的文档里有，下载完解压到~/.paddleocr/whl/对应的子目录下。目录结构大概是这样的：
~/.paddleocr/whl/ ├── det/ │ └── ch/ │ └── ch_PP-OCRv4_det_infer/ ├── rec/ │ └── ch/ │ └── ch_PP-OCRv4_rec_infer/ └── cls/ └── ch_ppocr_mobile_v2.0_cls_infer/放对位置之后，运行时就不会再去联网下载了。
3. 跑通第一个识别脚本并验证结果
装完之后，最激动人心的时刻就是跑第一个脚本。但我要提醒你，不要一上来就拿复杂的图片测试，先用一张干净的、白底黑字的截图，确认基础流程没问题，再逐步增加难度。
3.1 最简识别代码
from paddleocr import PaddleOCR ocr = PaddleOCR(use_angle_cls=True, lang='ch') result = ocr.ocr('test.png', cls=True) for line in result[0]: print(line[1][0], line[1][1])这段代码做了几件事：初始化 OCR 对象，开启方向分类，指定中文模型，然后对图片进行识别。result的结构是一个列表，每个元素对应一行文本，包含文本框坐标、识别文字和置信度。
第一次运行会稍微慢一点，因为要加载模型。如果一切正常，你会看到识别出来的文字和对应的置信度分数。
3.2 结果验证不能只看"有没有输出"
很多人跑出结果就以为成功了，其实不然。我总结了一套验证清单，每次装完新环境都会走一遍：
| 检查项 | 验证方法 | 合格标准 |
|---|---|---|
| 文字准确性 | 用已知内容的图片测试 | 识别结果与原文一致 |
| 置信度 | 查看输出的分数 | 清晰文字应在 0.95 以上 |
| 方向分类 | 用旋转 180 度的图片测试 | 能正确识别并纠正方向 |
| 多行文本 | 用段落截图测试 | 每行独立识别，顺序正确 |
| 边界情况 | 用空白图、纯色图测试 | 不报错，返回空结果 |
特别是最后一项，空白图测试经常被忽略。有些版本在遇到空白图时会抛异常，如果你没测过，上线后遇到用户传了张白图，程序直接崩了。
3.3 性能基准测试
如果你打算用于生产，还需要测一下速度。我的做法是准备 10 张不同复杂度的图片，循环识别 10 次，记录平均耗时：
import time times = [] for i in range(10): start = time.time() ocr.ocr('test.png', cls=True) times.append(time.time() - start) print(f"平均耗时: {sum(times)/len(times):.3f}秒")CPU 环境下，一张 1080P 的图片，检测加识别大概在 1 到 3 秒之间。GPU 环境下能降到 0.1 到 0.3 秒。如果你测出来慢得离谱，先检查是不是用了 CPU 版却以为自己在用 GPU。
4. 那些年我踩过的安装报错与排查思路
这一节是整篇文章最有价值的部分。下面这些报错，我几乎每个都遇到过至少一次，有的还不止一次。
4.1 "ImportError: libGL.so.1: cannot open shared object file"
这是 Linux 环境下最常见的报错，尤其是用 Docker 或者最小化安装的系统。原因是 opencv-python 依赖 libGL，但系统里没装。
解决方案有两个：
# 方案一：安装系统依赖 apt-get update && apt-get install -y libgl1-mesa-glx # 方案二：换用 headless 版本的 opencv pip uninstall opencv-python pip install opencv-python-headless我一般推荐方案二，因为 headless 版本不需要图形界面，更适合服务器环境，而且体积更小。
4.2 "AttributeError: module 'numpy' has no attribute 'int'"
这是 numpy 版本过高导致的。numpy 1.24 之后移除了np.int、np.float这些别名，但很多老代码还在用。PaddleOCR 某些版本就有这个问题。
解决方案是降级 numpy：
pip install numpy==1.23.5或者升级 PaddleOCR 到修复了这个问题的版本。我一般选择降级 numpy，因为升级 PaddleOCR 可能引入其他不兼容。
4.3 模型下载卡住或失败
国内网络环境下，自动下载模型经常超时。除了前面说的手动下载，还有一个办法是设置代理环境变量。但更稳妥的做法还是手动下载，一劳永逸。
如果你发现程序卡在 "Downloading..." 不动，直接 Ctrl+C 中断，然后去手动下载。下载地址在 PaddleOCR 的tools/infer/utility.py里能找到，搜索MODEL_URLS就能看到所有模型的下载链接。
4.4 GPU 版装了但用不了
这个问题的排查链路比较长，我一般按这个顺序查：
nvidia-smi能不能正常输出？不能的话是驱动问题。python -c "import paddle; paddle.utils.run_check()"输出里有没有 "GPU" 字样？没有的话说明装的是 CPU 版。- CUDA 版本和 PaddlePaddle 版本是否匹配？
post112对应 CUDA 11.2，装错了用不了。 - cuDNN 是否安装？版本是否匹配？
这四步走完，基本能定位到问题。我遇到过最坑的一次是驱动版本太老，nvidia-smi 能输出但 CUDA 版本不够，升级驱动后解决。
4.5 内存溢出
批量处理大图时，可能会遇到内存溢出。PaddleOCR 默认会把整张图加载到内存，图片特别大的时候就爆了。
解决方案是限制图片尺寸：
ocr = PaddleOCR( det_limit_side_len=960, # 限制检测输入尺寸 rec_image_shape="3, 48, 320" # 限制识别输入尺寸 )或者自己先对图片做缩放，再传给 OCR。我一般会把长边限制在 2000 像素以内，既能保证识别精度，又不会爆内存。
5. 装完之后怎么持续维护这套环境
安装只是开始，后续的维护同样重要。我见过太多人装完就不管了，结果过几个月想用的时候发现各种报错。
5.1 锁定依赖版本
装好之后，第一件事是导出当前环境的依赖清单：
pip freeze > requirements_lock.txt这个文件记录了你当前所有包的精确版本。以后环境出问题了，照着这个文件重装就能恢复。我一般会把 PaddlePaddle、PaddleOCR、numpy、opencv 这几个关键包的版本单独记下来，放在项目的 README 里。
5.2 定期检查模型更新
PaddleOCR 的模型迭代挺快的，PP-OCRv4 之后可能还会有 v5。新模型通常在精度和速度上都有提升，值得关注。但不要盲目升级，升级前先在测试环境验证，确认新模型在你的场景下确实更好再换。
5.3 建立自己的测试用例集
我建议每个用 PaddleOCR 的项目都建一个小的测试集，包含各种典型场景的图片：清晰文档、模糊照片、旋转文本、多语言混合、表格截图等。每次环境变动或者模型升级后，跑一遍测试集，对比识别结果，确保没有退化。
这个习惯帮我避免了好几次"升级后精度反而下降"的事故。有一次升级模型后，通用场景精度提升了，但我项目里特有的那种票据识别精度掉了好几个点，幸好测试集发现了。
5.4 关于 Docker 化的一点经验
如果你的项目要部署到多台机器，强烈建议做成 Docker 镜像。把 Python 版本、依赖、模型全部打包进去，一次构建到处运行，彻底告别"在我机器上能跑"的问题。
Dockerfile 的核心部分大概是这样：
FROM python:3.9-slim RUN apt-get update && apt-get install -y libgl1-mesa-glx libglib2.0-0 WORKDIR /app COPY requirements_lock.txt . RUN pip install -r requirements_lock.txt COPY . . CMD ["python", "app.py"]注意基础镜像用 slim 版本，体积小。系统依赖只装必要的，libgl 和 libglib 这两个是 opencv 需要的，不装会报错。
我自己在实际操作中的体会是，PaddleOCR 的安装测试看似简单，但真正要做好，需要把环境隔离、版本匹配、模型管理、性能验证这几件事都做到位。尤其是版本匹配这一环，是绝大多数问题的根源。装之前多花十分钟查版本对应关系，能省下后面几个小时的排查时间。另外，测试用例集这个习惯，越早建立越好，它会在你后续每一次环境变动时帮你兜底。
