【2025 最新版】Hugging Face 下载命令全教程（hf download 替代旧版，亲测有效）

前言近期许多用户发现网上旧版的 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-100hf download --repo-type dataset clane9/imagenet-100下载模型huggingface-cli download --repo-type model bert-base-uncasedhf download --repo-type model bert-base-uncased指定保存路径--local-dir ./data--local-dir ./data参数不变六、国内加速下载解决下载慢/超时方法1临时使用官方镜像运行下载命令前执行# Linux/Mac export HF_ENDPOINThttps://hf-mirror.com # Windows (CMD) set HF_ENDPOINThttps://hf-mirror.com # Windows (PowerShell) $env:HF_ENDPOINThttps://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数据集。