Python Package

huggingface-hub

2026-02-26

huggingface_hub 是 [[huggingface]] 官方提供的命令行工具，用于在终端中快速完成模型/数据集的下载、上传、登录认证等操作。

安装

通过 [[pip]] 安装:

Terminal window
pip install huggingface_hub

安装完成后在终端中执行 hf 命令使用（huggingface-cli 命令已弃用）。

参数

download

download 命令用于下载模型或数据集。

Terminal window
hf download <model_name>
  • model_name: 模型或数据集名称
  • —local-dir: 下载目录 (默认: ~/.cache/huggingface/hub)

cache

cache 命令用于管理已下载的模型或数据集。

Terminal window
hf cache <OPTIONS>
  • ls: 列出已下载的模型或数据集
  • rm: 删除已下载的模型或数据集
  • prune: 清理未使用的缓存
  • verify: 验证已下载的模型或数据集
Terminal window
# 删除模型
hf cache rm model/Qwen/Qwen3.5-27B-FP8

使用

修改超时设置

通过 huggingface-cli 下载模型过程中，如果出现: httpx.ReadTimeout: The read operation timed out 提示，可以修改 [[httpx]] 默认的超时设定:

Terminal window
export HF_HUB_DOWNLOAD_TIMEOUT=300

通过镜像加速下载

在终端中输入以下内容:

Terminal window
export HF_ENDPOINT=https://hf-mirror.com

然后再使用 hf download 命令下载镜像。

参考

# Python
# HuggingFace
# 模型
# CLI