企业官网建设流程全解析

Python 3.12 装 RapidOCR 失败？两步 pip 就能让 OCR 环境一次通过

【免费下载链接】RapidOCR📄 Awesome OCR multiple programing languages toolkits based on ONNX Runtime, OpenVINO, MNN, PaddlePaddle, TensorRT and PyTorch.项目地址: https://gitcode.com/GitHub_Trending/ra/RapidOCR

你在 Python 3.12 上跑新的 OCR 项目，pip installRapidOCR 的 API 组件，直接失败。现象不罕见：报错一长串，pip 把已下载的包全部回滚，最后什么都没装上。根因怎么定位、按什么顺序装才能过，一次给你交代清楚。

现场还原：pip 整包回滚

典型场面是这样的：你敲下pip install rapidocr_api，进度条跑完最后阶段，终端弹出类似这样的内容——

ERROR: Cannot install rapidocr_api 0.0.7 because these package versions have conflicting dependenciesrapidocr_onnxruntime 1.3.23 depends on Shapely (2.0.4, broken on Python 3.12)Rolling back: rapidocr_api, rapidocr_onnxruntime, Shapely

看到这几行的话，先别怀疑网络、镜像源或者 pip 版本，这是版本冲突，不是环境问题。

根因定位：Shapely 版本在 Python 3.12 上的冲突

一层层剥开看：

• 表层：pip 找不到一套满足所有约束的版本组合，于是整包回滚。
• 直接原因：旧版 rapidocr_onnxruntime 的依赖声明没有排除 Shapely 2.0.4，而 2.0.4 在 Python 3.12 上有已知缺陷，装上也跑不起来。
• 底层是依赖链：rapidocr_api 依赖 rapidocr_onnxruntime，后者再拖进 Shapely。这就是典型的依赖地狱（dependency hell，包与包之间版本互相锁死）。新 Python 版本发布后，底层依赖的适配总有一段空窗，底层没通，上层全部卡死。

修复已经落在新版依赖声明里：Shapely 约束放宽为Shapely>=1.7.1,!=2.0.4，可以在仓库的 python/requirements.txt 里直接核实。

修复路径：rapidocr_onnxruntime 依赖顺序安装步骤

1. 先装底层核心：pip install "rapidocr_onnxruntime>=1.3.24"。为什么排第一：它才是依赖链的核心，新版会带上 3.12 下可正常工作的 Shapely。
2. 再装上层组件：pip install rapidocr_api。此时解析器在环境里找到兼容的 Shapely，不再回滚。预期现象：安装一气呵成，无 rollback。
3. 验证：python -c "import rapidocr_api"，无报错即通过。

再次强调：先 rapidocr_onnxruntime、后 rapidocr_api，是硬顺序，不可调换。反了的话，旧版底层先被锁定，api 层只能迁就它，问题照样出现。

装通之后，拿一张样例图跑一次识别验证环境。仓库测试目录里就有现成的日语样本：

延伸一屏：依赖地狱

依赖地狱是 pip 生态的共性：依赖越多，越容易被彼此锁死。新版 Python 发布后，总会有一段窗口期，部分包的 wheel 还没构建好。同类坑还有Requires-Python区间不匹配、二进制 wheel 缺失。原则就一条：出错先看底层依赖，别急着换镜像。

避坑清单

• ✅ 装之前先升到最新稳定版：pip install -U rapidocr_onnxruntime
• ✅ 装前查项目更新日志，确认新 Python 版本是否已适配
• ✅ 核心依赖先装，上层组件后装，别一步到位装顶层
• ⚠️ 用虚拟环境隔离：python -m venv .venv，不同 Python 版本不要混用
• ⚠️ 生产环境选 3.10 / 3.11 更稳，尝鲜 3.13 建议走测试环境

两条命令，Python 3.12 下的安装环境就通了。这次修复的思路很直接——先修底层依赖，上层自然放行，反应快，没有绕弯。

【免费下载链接】RapidOCR📄 Awesome OCR multiple programing languages toolkits based on ONNX Runtime, OpenVINO, MNN, PaddlePaddle, TensorRT and PyTorch.项目地址: https://gitcode.com/GitHub_Trending/ra/RapidOCR