Hugging Face CLI

Hugging Face Hub 的官方 CLI 和 Python 客户端。
关于 · 文档 · 安装 · CLI 指南 · 参与贡献

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

快速开始

使用独立安装程序安装 hf CLI：

# On macOS and Linux.
curl -LsSf https://hf.co/cli/install.sh | bash

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

登录后即可开始使用 Hub：

# Log in (use --token $HF_TOKEN in non-interactive environments)
hf auth login

# Find models served by Inference Providers
hf models ls --warm

# Download a model
hf download Qwen/Qwen3-0.6B

# Upload files to your own repo
hf upload username/my-cool-model ./model.safetensors

# Sync a local folder to a storage bucket
hf buckets sync ./checkpoints hf://buckets/username/my-bucket

# Run a job on Hugging Face infrastructure
hf jobs run python:3.12 python -c "print('Hello from the cloud!')"

# Discover everything else
hf --help

Hub 使用令牌对应用程序进行身份验证（参阅文档）。查看 CLI 指南，了解主要功能。

什么是 huggingface_hub？

huggingface_hub 库让你能够与 Hugging Face Hub 交互。它是一个致力于让创作者和协作者都能使用开源机器学习的平台。你可以为项目发现预训练模型和数据集，体验 Hub 上托管的数千款机器学习应用，或者创建自己的模型、数据集和演示并与社区分享。所有功能都集成在一个软件包中，并提供两种接口：供终端使用的 hf CLI 和用于 Python 的 huggingface_hub 库，两者都旨在为人类和 AI Agent 提供良好的使用体验。你可以用它们来：

• 从 Hub 下载文件。
• 向 Hub 上传文件。
• 管理你的仓库。
• 在已部署的模型上运行推理。
• 在 Hugging Face 基础设施上运行任务。
• 搜索模型、数据集和 Spaces。
• 分享模型卡片，为你的模型编写文档。
• 通过 PR 和评论参与社区互动。
• 使用 hf CLI 在终端中完成以上所有操作。

为人类和 AI Agent 打造

hf CLI 同时面向使用者和编码 Agent 设计：由 Agent 运行时，相同的命令会自动调整输出。如果你使用 Claude Code、Codex、Cursor 或其他编码 Agent，请安装 hf CLI Skill——它是根据你安装的 CLI 生成的命令参考：

# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
hf skills add

更多信息请参阅面向 AI Agent 的 Hugging Face CLI 指南和公告博客文章。

使用 Python 库

使用 pip 安装 huggingface_hub 软件包（这也会安装 hf CLI）：

pip install huggingface_hub

我们建议使用 uv 进行快速、可靠的安装：

uv pip install huggingface_hub

为了让软件包默认保持精简，huggingface_hub 提供了一些适用于特定用例的可选依赖项。例如，如果你想使用 MCP 模块，请运行：

pip install "huggingface_hub[mcp]"

如需了解更多安装信息和可选依赖项，请参阅安装指南。

下载文件

下载单个文件

from huggingface_hub import hf_hub_download

hf_hub_download(repo_id="zai-org/GLM-5.2", filename="config.json")

或下载整个仓库

from huggingface_hub import snapshot_download

snapshot_download("sentence-transformers/all-MiniLM-L6-v2")

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

创建仓库

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 集成。

我们正在与优秀的开源 ML 库合作，为其提供免费的模型托管和版本管理。你可以在此处查看现有集成。

优势包括：

• 为库及其用户免费托管模型或数据集。
• 内置文件版本管理，即使是超大文件也适用，这得益于 Hub 基于分块去重的存储后端 Xet。
• 可在浏览器中使用的交互组件，让你体验上传的模型。
• 任何人都可以为你的库上传新模型；只需为模型添加对应标签，即可让其他人发现它。
• 下载速度快！我们使用 Cloudfront（CDN）在不同地理区域复制下载内容，因此无论身处地球何处，下载都飞快。
• 还将推出使用统计和更多功能。

如果你想集成自己的库，欢迎提出 issue 开始讨论。我们编写了分步指南，并附上 ❤️，说明如何完成此集成。

非常欢迎贡献（功能请求、错误报告等）💙💚💛💜🧡❤️

欢迎所有人参与贡献，我们珍视每个人的付出。帮助社区不只有编写代码这一种方式。 回答问题、帮助他人、积极沟通并改进文档，对社区都非常有价值。 我们编写了贡献指南，概述 如何开始为此代码库贡献。