huggingface_hub · Hugging Face Hub 官方 CLI 与 Python 客户端｜模型下载上传与推理全指南
项目仓库： https://github.com/huggingface/huggingface_hub
定位：Hugging Face Hub 官方 CLI（hf）与 Python 库 ·
安装：pip install huggingface_hub 或独立安装脚本 ·
官方文档：huggingface.co/docs/huggingface_hub
1 项目简介
huggingface_hub 是 Hugging Face Hub 的官方 CLI 与 Python
客户端：让你下载模型 / 数据集、上传文件、管理仓库、运行推理与
Jobs、搜索、写 Model Card、参与社区。一套工具同时提供终端
hf CLI 与 Python 库，为人类和 AI agent 设计。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | huggingface_hub |
| 仓库地址 | github.com/huggingface/huggingface_hub |
| 项目定位 | Hub 官方 CLI 与 Python 客户端 |
| 安装 | pip install huggingface_hub |
| CLI | hf |
| 官方文档 | huggingface.co/docs/huggingface_hub |
1.2 适用场景
- 本地命令行 / Python 脚本批量下载模型、上传权重。
- 让 AI coding agent（Claude Code / Codex / Cursor）通过 CLI 操作 Hub。
1.3 能力边界（官方口径）
- 包默认最小化，按需装可选依赖（如
pip install "huggingface_hub[mcp]"）。 - Hub 用 token 鉴权；下载走 CloudFront CDN 与 Xet 分块去重存储。
2 功能特性
- 下载文件 /
仓库：
hf_hub_download、snapshot_download。 - 上传文件 /
文件夹：
upload_file、upload_folder。 - 管理仓库、运行推理、跑 Jobs、搜索、Model Card、社区 PR。
- CLI 为 agent 设计：
hf skills add给 Claude Code / Codex / Cursor 等生成命令参考。
3 官方界面预览
CLI 工具，无图形界面；文档站有完整命令参考。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | https://github.com/huggingface/huggingface_hub | 源码 |
| 官方文档 | huggingface.co/docs/huggingface_hub | 指南 |
| CLI 指南 | huggingface.co/docs/huggingface_hub/en/guides/cli | CLI 命令 |
| 安装 | huggingface.co/docs/huggingface_hub/en/installation | 安装 |
| PyPI | pypi.org/project/huggingface-hub | 包 |
5 前置要求与服务器配置
5.1 软件前提
- Python 3.8+；pip 或 uv；网络访问 huggingface.co。
5.2 硬件建议
- 下载大模型需足够磁盘与带宽。
5.3 端口与资源
- 无服务端；纯客户端工具。
6 方式一：CLI 独立安装（推荐）
# 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"hf auth login
hf models ls --warm
hf download Qwen/Qwen3-0.6B
hf upload username/my-cool-model ./model.safetensors
hf --help7 方式二：pip 安装 Python 库
pip install huggingface_hub
# 或 uv
uv pip install huggingface_hubfrom huggingface_hub import hf_hub_download, snapshot_download
hf_hub_download(repo_id="zai-org/GLM-5.2", filename="config.json")
snapshot_download("sentence-transformers/all-MiniLM-L6-v2")8 配置项说明
- 用
hf auth login登录；非交互环境用--token $HF_TOKEN。 - 缓存目录见 manage-cache 文档。
9 常用运维命令
hf download/hf upload/hf jobs run/hf buckets sync。
10 常见故障排查
- 鉴权失败：检查 token；网络问题走镜像。
11 风险与合规说明
- 本文整理自官方 README，命令以官方文档最新说明为准；不包含 star 数等动态数据。