PaddleOCR 安装时因 faiss-cpu 编译失败报错，根本原因常为 Python 版本不兼容（如 3.11+），推荐降级至 Python 3.8–3.9 并使用 Conda 环境安装。

paddleocr 安装时因 `faiss-cpu` 编译失败报错，根本原因常为 python 版本不兼容（如 3.11+），推荐降级至 python 3.8–3.9 并使用 conda 环境安装。

faiss-cpu 是 PaddleOCR 可选依赖之一（尤其在启用向量检索、图像相似度等功能时被间接引入），但其官方 PyPI 包仅提供预编译 wheel 文件至 Python 3.10，且对 Python 3.11 及更高版本暂无官方支持。当你在 Python 3.11.5 环境中执行 pip install paddleclas（该包依赖 faiss-cpu）时，pip 会尝试从源码构建 wheel，而该过程极易因缺失 C++ 编译工具链、CUDA 配置冲突或 ABI 不匹配而失败，最终抛出：

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

✅ 推荐解决方案（稳定可靠）：

1. 创建独立的 Python 3.8/3.9 Conda 环境（强烈推荐）：

   conda create -n paddle_env python=3.8
   conda activate paddle_env

2. 按顺序安装核心依赖（避免版本冲突）：

   pip install --upgrade pip
   pip install paddlepaddle      # CPU 版（如需 GPU，请替换为 paddlepaddle-gpu）
   pip install paddleocr
   pip install paddleclas        # 此时 faiss-cpu 将自动安装预编译 wheel（Python 3.8 兼容）

⚠️ 注意事项：

• ❌ 不建议在 Python 3.11+ 下强行 --force-reinstall 或手动编译 faiss-cpu（易引发运行时崩溃或功能异常）；
• ✅ 若必须使用高版本 Python，可临时跳过 faiss-cpu（paddleclas 的部分高级功能将不可用）：

  pip install --no-deps paddleclas
  pip install paddlepaddle paddleocr  # 手动满足其余依赖

• ? 验证安装：运行 python -c "from paddleocr import PaddleOCR; print('OK')"，无报错即成功。

总结：PaddleOCR 生态对 Python 版本敏感，“降版本 + 换环境”是比“硬编译”更高效、更鲁棒的工程实践。优先选用 Conda 管理 Python 3.8–3.9 环境，可显著规避底层 C/C++ 扩展的兼容性问题。