huggingface_hub 入门实战：用 hf CLI 与 Python 客户端掌控 Hugging Face Hub

本篇技术指南以 Hugging Face Hub 官方 Python 客户端与 CLI 项目（huggingface_hub）为核心，系统讲解其双接口形态——终端下的 hf 命令与 Python 库 huggingface_hub。你将掌握独立安装器的用法、登录鉴权方式、常用 CLI 命令（下载、上传、模型搜索、存储桶同步、云端任务），以及用几行 Python 完成文件下载、仓库创建与上传的完整套路，并了解其为人类用户与 AI Agent 双重场景设计的底层机制。

一、huggingface_hub 是什么

huggingface_hub 库让你能与 Hugging Face Hub 直接交互。Hub 是一个面向开源机器学习创作者与协作者的平台：你可以在上面发现预训练模型与数据集，体验成千上万个托管应用，也可以创建并分享自己的模型、数据集和 Demo。

该项目将所有能力打包进一个包、提供两种界面：

• hf CLI：面向终端，命令简洁、输出友好；
• huggingface_hub Python 库：面向 Python 代码，函数式 API 与面向对象 API（HfApi）并存。

两者都"同时为人类和 AI Agent 设计"，可以完成以下工作：

能力	说明
下载文件	从 Hub 拉取单个文件或整个仓库
上传文件	向 Hub 上传单个文件或整个目录
管理仓库	创建、删除、移动、复制仓库
运行推理	调用已部署模型的推理服务
运行任务	在 Hugging Face 基础设施上运行或调度 Job
搜索	检索模型、数据集与 Spaces
分享模型卡片	用 Model Card 文档化你的模型
社区协作	通过 PR 与评论参与社区讨论
终端操作	上述能力几乎都能从终端完成

二、快速开始：安装 hf CLI

hf 是随包附带的官方命令行工具，推荐使用独立安装器（Standalone Installer）安装，它会在一个隔离的虚拟环境中部署 CLI，并通过软链暴露到 PATH。

macOS / Linux

curl -LsSf https://hf.co/cli/install.sh | bash

Windows（PowerShell）

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

从仓库内的 utils/installers/install.sh 可以看到安装器的完整行为：

• 依赖检查：要求 Python 3.10+，缺失时会针对 macOS、Debian/Ubuntu、Fedora/RHEL、CentOS 给出对应的安装提示；
• 安装位置：默认装在 $HOME/.hf-cli（虚拟环境 venv），若设置了 HF_HOME 则使用 $HF_HOME/cli；hf 命令的 wrapper 默认放在 ~/.local/bin（可用 HF_CLI_BIN_DIR 覆盖）；
• 加速安装：检测到 uv 时优先使用 uv pip install，否则回退到 pip；
• PATH 处理：自动向 .bashrc / .zshrc / fish 的 fish_user_paths 写入 wrapper 目录；
• 一键更新：hf update 会依据检测到的安装方式执行对应升级命令。

安装器支持的选项与环境变量如下（bash -s -- [OPTIONS] 形式传入）：

选项	作用
--force	已存在虚拟环境时强制重建
--no-modify-path	不自动修改 PATH
--with-transformers	同时安装 transformers 的 CLI
--exclude-skill	跳过为 AI Agent 安装 hf-cli skill
-v, --verbose	输出完整 pip 日志
HF_HOME	安装基础目录（使用 $HF_HOME/cli）
HF_CLI_BIN_DIR	hf wrapper 所在目录（默认 ~/.local/bin）

验证安装

hf --help

正确安装后会看到 auth、buckets、cache、collections、datasets、download、endpoints、jobs、models、papers、repos、skills、spaces、sync、upload 等命令分组。若出现 command not found: hf，通常是 PATH 未生效，source ~/.bashrc 或重启终端即可。

三、登录鉴权：Token 是唯一的钥匙

Hub 使用 Token 对应用进行鉴权。先登录：

# 交互式登录（会打开浏览器 / 提示粘贴 Access Token）
hf auth login

# 非交互环境（CI、Docker）直接用 Token：
# hf auth login --token $HF_TOKEN

从 src/huggingface_hub/cli/hf.py 中可以看到，auth 是一组懒加载命令组，底层由 huggingface_hub._login 的 login / logout / auth_list / auth_switch 等实现（见 src/huggingface_hub/_login.py 及 src/huggingface_hub/init.py 的 _SUBMOD_ATTRS 注册表）。

推荐做法：在非交互环境设置 HF_TOKEN 环境变量，CLI 与 Python 库都会自动读取，避免每次传 --token。

四、CLI 核心命令速览

登录后即可开始工作：

# 列出当前被至少一个推理提供商（Inference Providers）托管的模型
hf models ls --warm

# 下载一个模型到本地缓存
hf download Qwen/Qwen3-0.6B

# 上传文件到自己的仓库
hf upload username/my-cool-model ./model.safetensors

# 将本地目录与存储桶（Bucket）双向同步
hf buckets sync ./checkpoints hf://buckets/username/my-bucket

# 在 Hugging Face 基础设施上运行一个 Job
hf jobs run python:3.12 python -c "print('Hello from the cloud!')"

# 探索全部能力
hf --help

hf download：灵活的文件拉取

hf download <repo_id> <a href="https://link.gitcode.com/i/eb0a3b044cd067052246f4389e80ac3f" target="_blank">filenames...] 支持精确到单文件、子目录或整个仓库（实现位于 [src/huggingface_hub/cli/download.py）：

# 单文件
hf download meta-llama/Llama-3.2-1B-Instruct config.json tokenizer.json

# 用 glob 过滤
hf download meta-llama/Llama-3.2-1B-Instruct --include "*.safetensors" --exclude "*.bin"

# 下载到本地目录（而非共享缓存）
hf download meta-llama/Llama-3.2-1B-Instruct --local-dir ./models/llama

# 指定仓库类型（数据集）与子文件夹
hf download HuggingFaceM4/FineVision art/ --repo-type dataset

# 直接使用 hf:// URI（自动携带 repo-type 与 revision）
hf download hf://datasets/HuggingFaceH4/ultrachat_200k

关键参数：--repo-type {model|dataset|space}、--revision（分支/commit/tag）、--cache-dir（共享缓存目录）、--local-dir（一次性下载目录）、--include/--exclude（glob 模式）、--force-download、--dry-run（预演不实下）、--max-workers（默认 8 并发）、--token。

实现细节：单文件走 hf_hub_download，多文件/整仓走 snapshot_download（见 src/huggingface_hub/file_download.py 与 src/huggingface_hub/_snapshot_download.py）；以 / 结尾的子目录参数会被转换为 art/** 这类 include 模式；hf:// URI 解析由 parse_hf_uri 完成（src/huggingface_hub/utils/_hf_uris.py）。注意 --local-dir 与 --cache-dir 不能同时使用。

hf upload：文件与目录上传

hf upload <repo_id> <local_path> <path_in_repo> 支持通配符，默认将当前目录作为上传源（实现见 src/huggingface_hub/cli/upload.py）：

# 上传整个本地目录
hf upload my-cool-model . .

# 上传单个文件
hf upload Wauplin/my-cool-model ./models/model.safetensors

# 指定仓库类型与目标子路径
hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset

# 自定义 commit 信息
hf upload Wauplin/my-cool-model ./models . \
    --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%"

# 以 PR 形式提交，而不是直接写入主分支
hf upload bigcode/the-stack . . --repo-type dataset --create-pr

其他参数：--include/--exclude（glob 过滤）、--delete（提交时删除匹配的文件）、--revision、--private（创建私有仓库）、--every <minutes>（定时后台提交，例如训练过程中周期同步 checkpoint）。

注意：包含大量文件的目录会被拆分成多个 commit 提交；若上传被中断，重跑同一条命令即可断点续传。

hf models ls --warm：发现"可用"的模型

--warm 只列出当前至少被一个推理提供商托管的模型（定义于 src/huggingface_hub/cli/models.py），与 --pipeline-tag、--search、--sort、--limit、--expand=downloads,likes,tags 等组合使用：

hf models ls --pipeline-tag text-generation --warm
hf models ls --warm --search llama

hf buckets sync：本地与存储桶同步

hf buckets sync <source> <dest> 让本地目录与 hf://buckets/<namespace>/<bucket> 存储桶保持同步（实现见 src/huggingface_hub/cli/buckets.py）：

# 生成同步计划（不实际执行）
hf buckets sync ./data hf://buckets/user/my-bucket --dry-run

# 把计划写入文件，稍后统一执行
hf buckets sync ./data hf://buckets/user/my-bucket --plan sync-plan.jsonl
hf buckets sync --apply sync-plan.jsonl

# 删除目标端多余文件
hf buckets sync ./data hf://buckets/user/my-bucket --delete

同步时默认比较文件大小与修改时间，可用 --ignore-times（只看大小）或 --ignore-sizes（只看修改时间）调整判定策略。

hf jobs run：在云端跑任务

hf jobs run python:3.12 python -c "print('Hello from the cloud!')"

底层由 huggingface_hub._jobs_api 提供（run_job / create_scheduled_job / wait_for_job / fetch_job_logs 等，见 src/huggingface_hub/_jobs_api.py），可处理训练、数据管线、Agent 追踪等云端负载。

五、为人类与 AI Agent 设计的 CLI

hf CLI 的设计目标之一是与编码 Agent 无缝协作：同一命令由 Agent 执行时会自适应输出格式（--format agent / --format json）。

如果使用 Claude Code、Codex、Cursor 等支持从 .agents/skills 加载 skill 的 Agent，一条命令即可安装 CLI Skill——它是一份由你当前安装的 CLI 版本实时生成的命令参考文档：

# 适用于 Claude Code、Codex、Cursor、OpenCode、Pi 及任何从 .agents/skills 加载 skill 的 Agent
hf skills add

从 src/huggingface_hub/cli/skills.py 可以看到其实现机制：build_skill_md() 会遍历 CLI 命令树（hf.py 中注册的懒加载命令组），为每个叶子命令生成带参数类型提示的 Markdown 条目，再附上 --token、--quiet、--format 等公共选项说明，最后写入 .agents/skills（或 --global 时写入 ~/.agents/skills），并同步软链到 Claude Code 的 skills 目录。也就是说，skill 的内容始终与你的 CLI 版本保持一致。

hf skills list              # 查看已安装与市场上可用的 skill
hf skills add huggingface-gradio --dest=~/my-skills   # 从市场安装其它 skill
hf skills update            # 更新已安装的 skill（hf update 也会顺带刷新 hf-cli skill）
hf skills preview           # 直接把生成的 SKILL.md 打印到 stdout

独立安装器默认也会全局安装 hf-cli skill，--exclude-skill 可跳过。Agent 模式下还支持 hf <command> --help 获取完整参数说明，且鉴权推荐优先使用 HF_TOKEN 环境变量而非 --token。

六、使用 Python 库

pip install huggingface_hub 即可同时获得 Python 库与 hf CLI（CLI 入口在 src/huggingface_hub/cli/hf.py 定义）。推荐使用 uv 以获得更快、更可靠的安装：

pip install huggingface_hub
# 或
uv pip install huggingface_hub

为保持默认安装的轻量，部分可选能力通过 extras 提供，例如 MCP 模块（src/huggingface_hub/inference/_mcp/ 下的 Agent、MCPClient 等）：

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")

文件会落入本地缓存目录，默认路径由 HF_HOME（或 HF_HUB_CACHE）决定；缓存支持多版本复用与去重，可通过 huggingface_hub.utils 的 scan_cache_dir 与 hf cache 系列命令管理。单文件与快照下载的完整参数（revision、token、local_dir、max_workers、allow_patterns/ignore_patterns、dry_run 等）分别定义在 src/huggingface_hub/file_download.py 与 src/huggingface_hub/_snapshot_download.py。

创建仓库

from huggingface_hub import create_repo

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

create_repo 位于 src/huggingface_hub/hf_api.py 的 HfApi 类中，同名模块级函数由懒加载机制导出；它还支持 repo_type（model/dataset/space）、private、exist_ok 等参数。

上传文件

上传单个文件：

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",
)

两个函数都会自动处理大文件（走 LFS 预上传、分片传输），返回 CommitInfo（含 commit url 等信息）；文件夹上传同样支持 --every 式的定时提交（CommitScheduler，见 src/huggingface_hub/_commit_scheduler.py）。更完整的参数（revision、commit_message、create_pr、allow_patterns/ignore_patterns、max_workers、delete_patterns 等）见 src/huggingface_hub/hf_api.py 中 HfApi.upload_file 与 HfApi.upload_folder。

七、与其他库集成：免费托管与版本化

项目与大量开源 ML 库合作，为其提供免费的模型托管与版本管理。作为库作者集成后的收益：

• 为库及其用户提供免费模型/数据集托管；
• 内建文件版本化，即使超大文件也能依托 Xet——Hub 的按块去重存储后端（仓库内对应实现见 src/huggingface_hub/utils/_xet.py）实现；
• 模型页内嵌浏览器级交互 Widget；
• 任何人都能为你的库上传新模型，只需打上对应 tag 即可被发现；
• 借助 Cloudfront CDN 的地理复制，下载速度更快；
• 提供使用统计等能力。

八、进一步阅读

• CLI 完整参考（本仓库自带英文文档）
• CLI 指南：安装、登录、下载/上传、缓存管理、webhooks 等专题教程
• Python 包参考：hf_api、file_download、hf_file_system、inference_client、cache、repocard 等模块文档位于 docs/source/en/package_reference/
• 使用指南总览见 docs/source/en/guides/，覆盖下载、上传、仓库管理、推理、搜索、模型卡片、社区协作等主题

关键事实回顾：huggingface_hub 用一个包提供 hf CLI 与 Python 库双接口；CLI 命令采用懒加载注册（src/huggingface_hub/cli/hf.py 中的 _LAZY_COMMANDS / _LAZY_GROUPS），保证 --help 与 shell 补全的启动速度；hf skills add 生成的 skill 文档与本地 CLI 版本严格同步；Python API 模块级函数与 HfApi 类并存，由 __init__.py 中的懒加载注册表统一导出。上手最快路径是：独立安装器装 CLI → hf auth login → hf models ls --warm 找可用模型 → hf download 拉取 → 训练完成后 hf upload 分享。