buffalo 框架并不存在，实际需安装的是 insightface 中的 buffalo_l 模型资源包；它不是独立框架或可 pip 安装的库，而是 antelopev2 架构下的预训练模型 zip 文件，须手动下载解压至 ~/.insightface/models/antelopev2/ 并用 faceanalysis(name='antelopev2') 调用。

Buffalo 框架本身并不存在——你实际想装的是 insightface 里用到的 buffalo_l 模型资源包，不是独立框架。直接搜 “Buffalo 框架安装” 会走偏，因为没这个东西；所有相关文档、GitHub 仓库、模型下载链接，都指向 insightface 生态下的预训练模型资源。

为什么 pip install buffalo 或 conda install buffalo 都失败

因为没有名为 buffalo 的 PyPI 包或 conda channel 官方包。你看到的 buffalo_l 是 insightface 内部约定的模型标识符，对应一个 ZIP 文件，不是可 pip 安装的 Python 库。

• pip install buffalo 会装上一个同名但完全无关的推荐系统库（Apache Buffalo），和人脸无关
• insightface 本身不自动下载 buffalo_l，它只在首次调用时按需拉取，且默认走 GitHub Release 或 Hugging Face，网络不稳定就卡住
• 手动下载的 buffalo-l.zip 必须解压到 ~/.insightface/models/antelopev2/（新版）或 ~/.insightface/models/buffalo_l/（旧版），路径错一阶就加载失败

正确安装 buffalo_l 模型资源的三步实操

目标是让 FaceAnalysis 能静默加载模型，不报 FileNotFoundError: model not found 或卡在 downloading...。

Buffalo框架 1.0.1

Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。

下载

• 确认 insightface 已安装：pip install insightface（推荐 0.7.3+ 版本，兼容 antelopev2 架构）
• 手动下载 ZIP：https://www.php.cn/link/288cd13d1a5602b2174fbbcb728a49a3（截至 2026 年 9 月仍为最新稳定版）
• 解压后移动到标准路径：unzip buffalo-l.zip -d ~/.insightface/models/antelopev2/（注意不是 buffalo_l 子目录，而是直接进 antelopev2）

验证是否真装好了：用最简代码跑通

别依赖 WebUI 启动日志，那容易漏看模型加载失败的 warning。写一行测试脚本最可靠：

from insightface.app import FaceAnalysis
app = FaceAnalysis(name='antelopev2', root='~/.insightface')
app.prepare(ctx_id=0, det_size=(640, 640))
print("✅ 模型加载成功，det_size:", app.models['detection'].det_size)

如果输出带尺寸信息，说明 buffalo_l 对应的 antelopev2 检测+识别模型已就位；若报 KeyError: 'detection'，大概率是解压路径错了，或者 name 参数没配对（旧版用 name='buffalo_l'，新版统一为 'antelopev2'）。

真正容易被忽略的点：insightface 会缓存模型路径到 ~/.insightface/ 下的 SQLite 数据库里，如果你之前失败过多次，可能残留错误路径记录。遇到反复加载失败，直接删掉整个 ~/.insightface 目录再重试，比排查 cache 更快。