PaddleOCR 安装时因 faiss-cpu 编译失败报错，根本原因常是 Python 版本过高（如 3.11+）不兼容；降级至 Python ≤3.9（推荐 3.8）并使用 Conda 环境可彻底解决该问题。

paddleocr 安装时因 `faiss-cpu` 编译失败报错，根本原因常是 python 版本过高（如 3.11+）不兼容；降级至 python ≤3.9（推荐 3.8）并使用 conda 环境可彻底解决该问题。

在安装 PaddleOCR 及其生态组件（如 paddleclas）时，执行 pip install paddleclas 报出如下典型错误：

ERROR: Failed building wheel for faiss-cpu
Failed to build faiss-cpu
ERROR: Could not build wheels for faiss-cpu, which is required to install pyproject.toml-based projects

该错误并非 pip 本身故障，而是 faiss-cpu（Facebook 开发的高效相似性搜索库）在构建过程中依赖 C++ 编译工具链与特定 Python ABI 兼容性。关键限制在于：faiss-cpu 官方 PyPI 包仅提供预编译 wheel 文件至 Python 3.9（含）；Python 3.10+（尤其是 3.11/3.12）暂无官方支持 wheel，导致 pip 尝试从源码构建失败。

✅ 推荐解决方案（稳定、零编译、一步到位）：

1. 创建独立的 Python 3.8 Conda 环境（避免污染主环境）：

   

   AI舌诊面诊问诊医疗系统+诊疗商城系统源码

   AI 舌诊面诊问诊医疗系统 + 诊疗商城系统源码是一套结合 AI 辅助诊断与商品转化的健康类程序，基于浩创云、ThinkPHP（PHP）开发，支持微信服务号与 H5 端，适合做中医舌诊面诊问答、健康建议推送以及配套诊疗商品的运营。

   下载

   conda create -n paddle_ocr_env python=3.8
   conda activate paddle_ocr_env

2. 按顺序安装（确保依赖兼容性）：

   pip install --upgrade pip
   pip install paddlepaddle  # CPU 版（如需 GPU 版，请替换为 paddlepaddle-gpu）
   pip install paddleocr
   pip install paddleclas     # 此时将自动匹配兼容的 faiss-cpu 3.9- wheel

⚠️ 注意事项：

• 不要使用 pip install faiss-cpu 单独安装 —— paddleclas 会自动拉取与其版本锁定的 faiss-cpu（如 faiss-cpu==1.7.4），手动安装易引发版本冲突；
• 若必须使用高版本 Python（≥3.10），可尝试 conda install -c conda-forge faiss-cpu（Conda Forge 提供更广版本支持），但需同步切换整个生态为 Conda 安装（即 conda install paddlepaddle paddleocr paddleclas），不推荐混用 pip/conda；
• Windows 用户请确保已安装 Microsoft C++ Build Tools（若强制源码编译），但降级 Python 仍是首选方案。

? 总结：PaddleOCR 生态对 Python 版本敏感，faiss-cpu 是典型“卡点”依赖。坚持使用 Python 3.8 或 3.9 + Conda 环境，是当前最可靠、最省时的实践路径。 安装成功后，可通过以下代码快速验证：

from paddleocr import PaddleOCR
ocr = PaddleOCR(use_angle_cls=True, lang='en')
print("PaddleOCR 初始化成功！")