前言

近期许多用户发现网上旧版的 Hugging Face 下载教程已完全失效！
旧命令 huggingface-cli download 频繁出现报错或无法执行，核心原因是 huggingface-hub 库已完成重大更新，官方统一采用 hf 作为新命令行入口，替代了老旧的 huggingface-cli。

本文基于最新版工具实测（成功下载 clane9/imagenet-100 数据集），完全淘汰过时语法，适配 Linux/Windows/Mac 全平台，零基础可直接使用！

---

一、核心背景：为什么旧教程不能用了？

• 旧版工具：huggingface-cli（已被官方弃用为主命令）
• 新版工具：hf（官方推荐的统一命令行工具，集成下载、上传、管理功能）

旧版典型报错：

1. command not found: huggingface-cli
2. 解释器路径错误
3. 命令执行后无任何响应

解决方案：卸载旧工具，安装最新版 huggingface-hub，使用 hf download 命令！

---

二、环境准备（一步到位）

1. 安装/更新核心库

激活 Conda 环境（推荐），执行以下命令强制更新：

# 安装/更新最新版 huggingface-hub（必须）
pip install -U --force-reinstall huggingface-hub

2. 验证安装成功

输入以下命令，出现版本号即表示成功：

# 查看新版工具版本
hf --version

---

三、新版核心命令：hf download 全用法

官方语法

hf download [参数] 仓库ID

关键参数（必看）

Hugging Face 分为三类仓库，下载时必须指定类型：

参数	含义	使用场景
--repo-type model	模型仓库	下载 Transformer、LLM、视觉模型
--repo-type dataset	数据集仓库	下载 ImageNet、CIFAR 等数据集（⭐本文重点）
--repo-type space	应用空间	下载 Gradio/Streamlit 项目

---

四、实战下载（亲测可用示例）

示例1：下载数据集（ImageNet-100）

# 下载 clane9/imagenet-100 数据集（完整版）
hf download --repo-type dataset clane9/imagenet-100

示例2：下载模型（通用场景）

# 下载 bert-base-uncased 模型
hf download --repo-type model bert-base-uncased

示例3：指定下载路径

# 数据集保存到 ./data/imagenet-100 文件夹
hf download --repo-type dataset clane9/imagenet-100 --local-dir ./data/imagenet-100

示例4：仅下载单个文件

# 仅下载 train.csv 文件
hf download --repo-type dataset clane9/imagenet-100 train.csv

---

五、旧版 VS 新版命令对照表

场景	旧版命令（失效）	新版命令（推荐）
下载数据集	huggingface-cli download --repo-type dataset clane9/imagenet-100	hf download --repo-type dataset clane9/imagenet-100
下载模型	huggingface-cli download --repo-type model bert-base-uncased	hf download --repo-type model bert-base-uncased
指定保存路径	--local-dir ./data	--local-dir ./data（参数不变）

---

六、国内加速下载（解决下载慢/超时）

方法1：临时使用官方镜像

运行下载命令前执行：

# Linux/Mac
export HF_ENDPOINT=https://hf-mirror.com

# Windows (CMD)
set HF_ENDPOINT=https://hf-mirror.com

# Windows (PowerShell)
$env:HF_ENDPOINT="https://hf-mirror.com"

方法2：永久配置镜像

hf config set HF_ENDPOINT https://hf-mirror.com

---

七、常见问题解决

问题1：-bash: hf: command not found

原因：未激活 Conda 环境或安装未生效
解决：

conda activate 你的环境名
pip install -U huggingface-hub

问题2：权限报错（401 Unauthorized）

原因：私有仓库需登录
解决：

# 输入 Access Token 登录
hf auth login

问题3：下载中断/不完整

解决：添加 --resume 参数断点续传

hf download --repo-type dataset clane9/imagenet-100 --resume

---

八、总结

1. 2025 最新命令：hf download 完全替代 huggingface-cli；
2. 仓库类型必填：数据集用 --repo-type dataset，模型用 --repo-type model；
3. 国内加速：必须配置镜像（hf-mirror.com）；
4. 实测有效：本文命令已成功下载 clane9/imagenet-100 数据集。

---