前言
近期许多用户发现网上旧版的 Hugging Face 下载教程已完全失效！
旧命令huggingface-cli download频繁出现报错或无法执行，核心原因是huggingface-hub库已完成重大更新，官方统一采用hf作为新命令行入口，替代了老旧的huggingface-cli。
本文基于最新版工具实测（成功下载clane9/imagenet-100数据集），完全淘汰过时语法，适配 Linux/Windows/Mac 全平台，零基础可直接使用！
一、核心背景：为什么旧教程不能用了？
- 旧版工具：
huggingface-cli（已被官方弃用为主命令） - 新版工具：
hf（官方推荐的统一命令行工具，集成下载、上传、管理功能）
旧版典型报错：
command not found: huggingface-cli- 解释器路径错误
- 命令执行后无任何响应
解决方案：卸载旧工具，安装最新版huggingface-hub，使用hf download命令！
二、环境准备（一步到位）
1. 安装/更新核心库
激活 Conda 环境（推荐），执行以下命令强制更新：
# 安装/更新最新版 huggingface-hub（必须） pip install -U --force-reinstall huggingface-hub2. 验证安装成功
输入以下命令，出现版本号即表示成功：
# 查看新版工具版本 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 login问题3：下载中断/不完整
解决：添加--resume参数断点续传
hf download --repo-type dataset clane9/imagenet-100 --resume八、总结
- 2025 最新命令：
hf download完全替代huggingface-cli； - 仓库类型必填：数据集用
--repo-type dataset，模型用--repo-type model； - 国内加速：必须配置镜像（
hf-mirror.com）； - 实测有效：本文命令已成功下载
clane9/imagenet-100数据集。
