Hugging Face

发布于 2026-10-01更新于 2026-10-06

hf 命令行

hf 是 Hugging Face 官方命令行工具(由 huggingface_hub 提供),用于与 Hugging Face Hub 交互,完成登录、仓库管理以及模型和数据集下载;本文记录其安装、更新、hf download 用法,以及默认缓存目录与 --local-dir 本地目录模式的区别。

介绍

hf 是 huggingface_hub Python 库提供的内置 CLI 工具。

通过该工具可以直接在命令行中与 Hugging Face Hub 进行交互,包括但不限于:登录、创建仓库、下载文件等;

安装

官方推荐使用一条命令安装,也可使用 uv、pip、homebrew 等工具安装。

  • macOS 和 Linux
Bash
curl -LsSf https://hf.co/cli/install.sh | bash
  • Windows
Bash
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

安装包会同时安装全局 hf-cli skill,供任何读取 ~/.agents/skills 目录的 agent 使用。

如果不需要,使用 --exclude-skill 参数可以避免安装:

Bash
# 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"

安装完成后,使用如下命令进行验证;

Bash
hf --help

更新

更新到最新版本,该命令会自动检测是通过何种方式安装的,并进行相应的更新。

Bash
hf update

hf download

命令格式:

Bash
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;

Bash
hf download tencent/Hy-MT2-7B --local-dir ~/MyFiles/models/tencent/Hy-MT2-7B

下载文件到指定目录

  • 下载一个文件到指定目录:
Bash
hf download JonathanColetti/Qwen3.8-27B-Uncensored-GGUF Qwen3.8-27B-Uncensored-Q5_K_M.gguf --local-dir ~/<local-path>/Qwen/qwen3.8
  • 下载多个文件到指定目录:
Bash
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
  • 下载整个仓库到指定目录:
Bash
hf download tencent/Hy-MT2-7B --local-dir ~/<local-path>/tencent/Hy-MT2-7B

链接