如何解决 PaddleOCR 安装中 faiss-cpu 编译失败问题

PaddleOCR 安装报错 Failed building wheel for faiss-cpu，根本原因通常是 Python 版本过高（如 3.11+）导致 faiss-cpu 不兼容；降级至 Python ≤3.9（推荐 3.8）并使用 Conda 环境可彻底解决。

paddleocr 安装报错 `failed building wheel for faiss-cpu`，根本原因通常是 python 版本过高（如 3.11+）导致 faiss-cpu 不兼容；降级至 python ≤3.9（推荐 3.8）并使用 conda 环境可彻底解决。

在安装 PaddleOCR 生态相关库（如 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 开发的高效相似性搜索库，被 paddleclas 依赖）尚未为 Python 3.10/3.11 提供预编译 wheel 包，且其源码编译对高版本 Python 支持不完善——尤其在 Windows 或部分 Linux 环境下缺少对应编译工具链时，极易失败。

✅ 推荐解决方案：使用 Python 3.8 + Conda 环境（最稳定可靠）

文心一言

文心一言是百度开发的AI聊天机器人，通过对话可以生成各种形式的内容。

下载

# 1. 创建独立的 Python 3.8 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

⚠️ 注意事项：

• ❌ 避免在 Python ≥3.10 的环境中强行编译 faiss-cpu：即使安装了 cmake、swig、g++ 等工具，仍大概率因 ABI 不兼容或 PyBind11 版本冲突而失败；
• ✅ 若必须使用较新 Python 版本（如 3.10），可尝试跳过 faiss-cpu 的直接依赖：paddleclas 在非检索类任务中并非必需；或改用 pip install paddleclas --no-deps 后手动安装兼容版本（如 faiss-cpu==1.7.4，仅支持至 Python 3.9）；
• ? 国内用户建议配置清华镜像源加速安装：

  pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

? 总结：PaddleOCR 官方生态（含 paddleclas）当前（截至 2025 年）明确要求 Python ≤3.9。将环境切换至 Python 3.8 是成本最低、成功率最高的实践方案。开发前务必验证环境：python --version 和 pip list | grep -i "paddle\|faiss"，确保各组件版本协同无冲突。