企业官网建设流程全解析

RapidOCR 在 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

在 Python 3.12 环境里装rapidocr_api，经常装到一半就报错退出。这是 RapidOCR 安装时最常被卡住的一类兼容问题，和 3.12 本身没毛病。按下面的顺序操作，两条命令就能把环境搭好，装完后检测、识别功能都能正常跑。

谁会遇到这篇：症状自查

先对号入座，满足下面三条，基本就是同一个坑：

• 解释器是 Python 3.12.x，不是 3.10 或 3.11。
• 你执行的是pip install rapidocr_api==0.0.7，且装到依赖解析阶段就失败。
• 报错信息里出现shapely/Shapely字样，或卡在某个 C 扩展编译不上。

三条全中，往下看即可，不用折腾环境。如果你装的是最新版、环境也新，多半一次就过，这篇帮不上忙。

根因 60 秒讲清

问题出在依赖链最底层，不在 RapidOCR 代码本身。rapidocr_api会拉起文本检测模块，检测模块用到了几何库shapely来算多边形框；在 Python 3.12 下，旧版 shapely 的预编译包和 C 扩展对不上号，就装不上。

打个比方：底层那块积木已经换代，上层模块还拿着旧接口的图纸去找，自然拼不到一起。

这个冲突在项目的 python/requirements.txt 里能直接看到：Shapely>=1.7.1,!=2.0.4，注释写着python3.12 2.0.4 bug。也就是说 2.0.4 这个版本在 3.12 上有坑，官方已经明确把它排除了。shapely 具体在哪儿被用到，可以看 python/rapidocr/ch_ppocr_det/utils.py 里的from shapely.geometry import Polygon。

修复操作 + 如何验证装好了

👇 关键只有一句话：先装 onnxruntime，再装 api，顺序不能反。

先装 rapidocr_onnxruntime 再装 rapidocr_api

onnxruntime 是整条链里最底层、也最容易被卡住的部件，先把它的版本提到 1.3.24 及以上：

pip install "rapidocr_onnxruntime>=1.3.24"

确认它装好后，再装 API 层：

pip install rapidocr_api

Shapely 冲突怎么确认

装完做两步验证。第一，终端里执行import rapidocr_api，不报错就对了；再用pip show rapidocr_onnxruntime看一眼，版本应在 1.3.24 或更高。第二，拿一张文字图跑一遍 OCR，能正常返回文本，说明检测、识别整条链路都通了。下面这张就是仓库自带的测试样例：

变体问题：如果还报别的错

装到第二步又失败，多半是 shapely 版本没排干净，按这个顺序排查：

• 用pip show shapely查当前版本。若是 2.0.4，先卸掉再让 pip 重新解析；它本来就不该出现在 3.12 里。
• 报缺依赖或解析残留，多是 pip 缓存导致，加--upgrade或清一下缓存再装一遍。
• 若rapidocr_onnxruntime自己装不上，多半是网络或镜像问题，换官方或就近源，别在版本上继续降。

多数情况走完前两条就装好了。真到要动 shapely 版本时，记住一条：跟着 requirements.txt 的约束走，别自己猜版本。

延伸：顺手可以做的配置

📌 这四个习惯，能让类似问题以后不再找上你：

• 优先最新稳定版。装依赖时别锁死旧号，先试最新稳定版，多数兼容问题官方已经处理了。
• 看更新日志。升级前先扫一眼 changelog，版本兼容信息一般写在里面。
• 核心依赖先行。像 onnxruntime 这种底层部件，先单独装好、确认版本，再往上叠。
• 用虚拟环境隔离。每个项目一个 venv，3.12 的坑不会串到别的解释器里去。

按 onnxruntime 在前、api 在后的顺序装完，RapidOCR 即可正常使用全部功能。

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