ImportError: cannot import name ‘HfFolder’ from ‘huggingface_hub’

问题场景

用户在 Windows 11 上克隆 TextGen WebUI 仓库，创建独立 Python venv，按 requirements/portable/requirements.txt 安装依赖后，运行 python server.py --portable --api --auto-launch 启动服务时触发导入错误。报错发生在 server.py 导入 modules.shared、再经 modules.presets 与 modules.loaders 的导入链中。

报错原文

ImportError: cannot import name 'HfFolder' from 'huggingface_hub'

原因分析

最可能的原因是当前安装的 huggingface_hub 版本与 TextGen WebUI 代码期望的接口不一致，导致 HfFolder 无法从 huggingface_hub 导入。Issue 评论中通过降级到 0.x 版本后恢复正常，说明版本不匹配是主要排查方向；但具体是哪个依赖引入了不兼容版本，Issue 中未给出完整证据。

环境排查

• 确认当前 venv 是否确实被激活，以及 pip 是否指向该 venv 内的 Python。
• 确认已安装的 huggingface_hub 版本，判断是否处于 0.x 还是更高版本。
• 确认 transformers 等依赖的版本，因为评论指出降级 huggingface_hub 后可能与 transformers 出现不兼容。
• 确认安装时使用的是 requirements/portable/requirements.txt 对应的硬件依赖文件。
• Python、CUDA、PyTorch、显卡驱动版本在 Issue 中未提供，排错时可一并记录以便复现。

解决步骤

1. 先检查当前 venv 中 huggingface_hub 的版本，确认是否与 TextGen WebUI 当前代码不匹配。
2. 按 Issue 评论中的方向，尝试将 huggingface_hub 降级到 0.x 版本；评论中给出的具体版本为 0.34.3。由于该版本号和完整安装命令未在 Issue 正文中逐字复现，执行前请自行核对来源。
3. 降级后重新启动 server.py，观察导入链是否还停留在 modules.loaders 阶段。
4. 如果出现 transformers 等包的不兼容报错，记录冲突包及版本，再评估是否回退或改用其他兼容组合；Issue 中未给出已验证的替代方案。
5. 评论中提出将旧版 HfFolder 合并进新版 huggingface_hub，这只是提问者的设想，未经验证，不建议作为首选修复。

验证方法

重新运行启动命令后，如果不再出现 ImportError: cannot import name 'HfFolder' from 'huggingface_hub'，并且服务能继续加载模块、进入启动流程，即可认为该导入错误已解决；同时应检查是否引入新的依赖冲突报错。

参考来源

oobabooga/textgen #7284

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。