Hugging Face Hub 的官方 Python 客户端。

English | Deutsch | Français | हिंदी | 한국어 | 中文 (简体)

---

文档: https://hf.co/docs/huggingface_hub

源代码: https://github.com/huggingface/huggingface_hub

---

欢迎使用 huggingface_hub 库

huggingface_hub 库使您能够与 Hugging Face Hub 进行交互，这是一个为创作者和合作者普及开源机器学习的平台。您可以发现用于项目的预训练模型和数据集，或试用 Hub 上托管的数千个机器学习应用。您还可以创建并分享自己的模型、数据集和演示作品给社区。huggingface_hub 库提供了一种简单的方法，让您通过 Python 实现所有这些操作。

核心功能

• 从 Hub 下载文件。
• 向 Hub 上传文件。
• 管理您的 仓库。
• 对已部署的模型进行 推理。
• 搜索模型、数据集和 Spaces 空间。
• 分享 模型卡片，以记录您的模型信息。
• 通过 PR 和评论与社区互动 参与社区。

安装

使用 pip 安装 huggingface_hub 包：

pip install huggingface_hub

如果您更喜欢，也可以使用 conda 进行安装。

为了保持包的默认最小化，huggingface_hub 带有针对某些用例的可选依赖项。例如，如果您想使用 MCP 模块，请运行：

pip install "huggingface_hub[mcp]"

有关更多安装信息及可选依赖项，请参阅 安装指南。

快速入门

下载文件

下载单个文件：

from huggingface_hub import hf_hub_download

hf_hub_download(repo_id="tiiuae/falcon-7b-instruct", filename="config.json")

或者下载整个仓库：

from huggingface_hub import snapshot_download

snapshot_download("stabilityai/stable-diffusion-2-1")

文件将被下载到本地缓存文件夹中。更多详情请参阅 此指南。

登录

Hugging Face Hub 使用令牌来验证应用程序（详见 文档）。要登录您的设备，请运行以下 CLI：

hf auth login
# 或者使用环境变量
hf auth login --token $HUGGINGFACE_TOKEN

创建仓库

from huggingface_hub import create_repo

create_repo(repo_id="super-cool-model")

上传文件

上传单个文件：

from huggingface_hub import upload_file

upload_file(
    path_or_fileobj="/home/lysandre/dummy-test/README.md",
    path_in_repo="README.md",
    repo_id="lysandre/test-model",
)

或者上传整个文件夹：

from huggingface_hub import upload_folder

upload_folder(
    folder_path="/path/to/local/space",
    repo_id="username/my-cool-space",
    repo_type="space",
)

详细信息请参阅 上传指南。

集成到 Hub

我们正与优秀的开源机器学习库合作，为其提供免费的模型托管和版本控制服务。您可以在 这里找到现有的集成。

其优势包括：

• 为库及其用户免费托管模型或数据集。
• 内置文件版本控制，即使是超大文件也能轻松处理，这得益于基于 Git 的方法。
• 浏览器内小工具，方便您试用上传的模型。
• 任何人都可以为您的库上传新模型，只需添加相应的标签，即可让该模型被发现。
• 下载速度快！我们使用 Cloudfront（CDN）对下载进行地理复制，因此无论您身处何地，都能极速下载。
• 使用统计等更多功能即将推出。

如果您希望将您的库集成到 Hugging Face Hub，请随时提交一个问题以开始讨论。我们编写了一份充满爱意的 分步指南，展示了如何完成这一集成。

欢迎大家贡献代码、提出功能需求、报告 bug 等 💙💚💛💜🧡❤️

我们欢迎所有人参与贡献，并珍视每一位贡献者的努力。为社区贡献力量的方式不止于编写代码。 解答问题、帮助他人、主动联系并完善文档，对社区同样具有极大的价值。 我们撰写了一份贡献指南，总结了如何开始为本仓库做出贡献。

huggingface_hub 快速上手指南

huggingface_hub 是 Hugging Face Hub 的官方 Python 客户端，帮助开发者轻松下载模型、上传文件、管理仓库以及运行推理。

环境准备

• 操作系统：Windows, macOS, Linux
• Python 版本：3.8 及以上
• 前置依赖：需安装 pip 或 conda 包管理器
• 网络建议：国内用户若访问缓慢，可配置镜像源或使用代理加速

安装步骤

使用 pip 安装（推荐）：

pip install huggingface_hub

如需使用可选功能（如 MCP 模块），可安装扩展依赖：

pip install "huggingface_hub[mcp]"

国内用户可使用清华镜像源加速安装：

pip install huggingface_hub -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 下载文件

下载单个文件：

from huggingface_hub import hf_hub_download

hf_hub_download(repo_id="tiiuae/falcon-7b-instruct", filename="config.json")

下载整个仓库：

from huggingface_hub import snapshot_download

snapshot_download("stabilityai/stable-diffusion-2-1")

文件将默认保存至本地缓存目录。

2. 登录认证

使用前需通过 Token 登录：

hf auth login
# 或通过环境变量指定 token
hf auth login --token $HUGGINGFACE_TOKEN

Token 可在 Hugging Face 官网 获取。

3. 创建仓库

from huggingface_hub import create_repo

create_repo(repo_id="super-cool-model")

4. 上传文件

上传单个文件：

from huggingface_hub import upload_file

upload_file(
    path_or_fileobj="/home/lysandre/dummy-test/README.md",
    path_in_repo="README.md",
    repo_id="lysandre/test-model",
)

上传整个文件夹：

from huggingface_hub import upload_folder

upload_folder(
    folder_path="/path/to/local/space",
    repo_id="username/my-cool-space",
    repo_type="space",
)

---

更多高级用法请参考 官方文档。