企业官网建设流程全解析

RapidOCR Python 3.12 安装失败？3 步搞定 rapidocr_api 报错

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

RapidOCR Python 3.12 安装时执行pip install rapidocr_api，会卡在依赖解析阶段报错，日志基本都指向 Shapely（一个做几何坐标计算的库）。这是很典型的 rapidocr_api 安装报错：根源不在你的环境，而是 Shapely 停在旧版本，跑不了 3.12。按下面 3 步走，很快搞定。

3 步修复 rapidocr_api 安装报错

先给答案：

1. 装 rapidocr_onnxruntime（底层模型运行库），版本锁定 1.3.24 及以上
2. 再装 rapidocr_api
3. 导入验证一下

就这三步，顺序别反。为什么是这个顺序，往下看。

Shapely 不兼容 Python 3.12 是怎么回事

一个包的依赖是串成一条链的：rapidocr_api 依赖 onnxruntime（真正执行模型推理的运行环境），onnxruntime 又依赖 Shapely 这类几何库。这条链就叫依赖链。

你可以把它想象成接力赛，接力棒要一节一节往下传。旧版 rapidocr_api 锁定了老 Shapely。老 Shapely 只认低版本 Python，在 3.12 上装不上。整条链断在一环，pip 只能报错退出。

修法其实很简单。新版 rapidocr_onnxruntime（1.3.24 起）换上了适配 3.12 的依赖版本。所以先把它装上，pip 就会挑一个能用的新版 Shapely。之后再装 rapidocr_api，链条自然顺了。

RapidOCR Python 3.12 安装：手把手命令与预期结果

⚠️ 建议开个虚拟环境再操作，别把系统 Python 弄乱。

第 1 步：先装底层运行库

pip install "rapidocr_onnxruntime>=1.3.24"

这一步把模型运行库升到兼容 3.12 的版本，顺带把新版 Shapely 拉下来。

第 2 步：再装 rapidocr_api

pip install rapidocr_api

依赖链已经打通，这步应该直接装完，不再报版本冲突。

第 3 步：导入验证

python -c "import rapidocr_api; print('OK')"

✅ 终端打出OK就说明装好了。仓库里自带测试图，比如 python/tests/test_files/，随便拿一张跑次识别，能吐出文字就齐活了。

Python 3.12 依赖问题通用排查方法

这次踩的坑不是孤例。下次再遇到类似的依赖报错，按这个流程走：

• 看日志最后几行：pip 报错末尾一般有 "ERROR: Could not find a version" 字样。后面跟着的库名就是元凶（这次是 Shapely）。定位问题全靠它
• 先装核心依赖：上层包卡住时，手动把底层库升到位，再装上层组件，往往直接绕开冲突
• 查更新日志：看看项目是否已发新版修掉这个依赖问题。API 组件的安装说明见 api/README.md，项目文档在 docs/
• 虚拟环境隔离：新环境里复现问题，不污染其他项目，出问题直接重建

RapidOCR 团队已经在新版本里修掉了 Shapely 版本不兼容的问题。以后遇到安装失败，直接装最新版就行。

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