介绍
hf 是 huggingface_hub Python 库提供的内置 CLI 工具。
通过该工具可以直接在命令行中与 Hugging Face Hub 进行交互,包括但不限于:登录、创建仓库、下载文件等;
安装
官方推荐使用一条命令安装,也可使用 uv、pip、homebrew 等工具安装。
- macOS 和 Linux
curl -LsSf https://hf.co/cli/install.sh | bash- Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"安装包会同时安装全局 hf-cli skill,供任何读取 ~/.agents/skills 目录的 agent 使用。
如果不需要,使用 --exclude-skill 参数可以避免安装:
# macOS 和 Linux
curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill
# Windows
powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill"安装完成后,使用如下命令进行验证;
hf --help更新
更新到最新版本,该命令会自动检测是通过何种方式安装的,并进行相应的更新。
hf updatehf download
命令格式:
hf download [OPTIONS] REPO_ID [FILENAMES]...
# 也可以通过帮助查看
hf download --help若不指定 --local-dir 参数,默认会下载到 Hugging Face 的缓存目录,即 ~/.cache/huggingface/hub,由 HF_HOME 环境变量指定。
目录结构是为「多版本共享、去重」设计的,而不是为了方便人阅读设计的:
models--Qwen--Qwen3.8-27B/
├── blobs/ # 实际文件内容,以哈希值命名
├── refs/ # 分支名 → commit 哈希的映射(如 main)
└── snapshots/
└── <commit_hash>/
└── config.json → 符号链接,指向 ../../blobs/<hash>指定 --local-dir 本地目录模式,文件按仓库原本的目录结构直接放到指定的路径下,是真实文件而不是符号链接,可以直接移动、拷贝、打包,也方便离线部署;
使用时注意:--local-dir 指定的是文件的最终存放目录,hf 不会自动按仓库名(org/name)创建子目录。比如指定 ~/MyFiles/models,模型的所有文件会直接平铺在这一层,下载多个模型后就会混在一起。
最好的方式是:让本地路径与仓库 ID 保持一致,即 <根目录>/<org>/<name>,比如 ~/MyFiles/models/JonathanColetti/Qwen3.8-27B-Uncensored-GGUF;
hf download tencent/Hy-MT2-7B --local-dir ~/MyFiles/models/tencent/Hy-MT2-7B下载文件到指定目录
- 下载一个文件到指定目录:
hf download JonathanColetti/Qwen3.8-27B-Uncensored-GGUF Qwen3.8-27B-Uncensored-Q5_K_M.gguf --local-dir ~/<local-path>/Qwen/qwen3.8- 下载多个文件到指定目录:
hf download JonathanColetti/Qwen3.8-27B-Uncensored-GGUF \
Qwen3.8-27B-Uncensored-Q5_K_M.gguf \
mmproj-Qwen3.8-27B-Uncensored-F16.gguf \
--local-dir ~/<local-path>/Qwen/qwen3.8- 下载整个仓库到指定目录:
hf download tencent/Hy-MT2-7B --local-dir ~/<local-path>/tencent/Hy-MT2-7B