如果你和我一样平时经常要下载各种开源模型和数据集那你对 Hugging Face 绝对不陌生。以前下载模型总会遇到transformers-cli不好使、huggingface-cli download参数记不住、下载到一半断连又得从头再来之类的破事。2026 年再回头看Hugging Face 官方已经把命令行的重点转移到了hf download上这套命令确实比旧版更直观也更好用。我把自己在这段时间里实际踩过的坑、反复验证过的命令和参数整理出来了这篇教程适合所有要在命令行里下载模型、数据集、Space 仓库甚至代码文件的同学。无论你是在本地电脑还是在 Linux 服务器上跑训练照着做都能少走不少弯路。1. 先说清楚hf download 到底是来替代什么的1.1 旧命令为什么会让人崩溃Hugging Face 的 Python 库huggingface_hub从很早期就提供了命令行工具最初大家常用的是transformers-cli后来慢慢迁移到huggingface-cli download。问题在于这些命令在不同版本里行为不一致有的版本默认下载到缓存目录有的版本要求你手动指定--local_dir有的版本还需要额外加--local-dir-use-symlinks否则文件会被链接得七拐八绕。对一个只想把模型拿到手的人来说这些差异实在太劝退了。更烦的是很多人习惯直接在浏览器里点官网的“下载”按钮一看模型明明只有几百 MB等下载完才发现还要把一堆分片文件手动拼回去。碰到像 LLaMA、Mistral 这种动辄几十 GB 的大模型浏览器下载基本是死路一条随时断连。旧版命令行虽然能断点续传但中断之后你往往分不清是缓存文件损坏了还是压根没下载完。那时候我常用的办法是删掉目录重新下白白浪费几个小时。1.2 新 CLI 的设计思路hf download的核心变化是把“下载”这个动作收敛成了一条主命令。所有仓库类型都能通过显式的--repo-type区分model是模型dataset是数据集space是 Space 应用其他代码仓库也有对应类型。你不需要再去记transformers-cli还是huggingface-cli这种历史包袱只需要知道hf这一个入口。这个设计思路其实是把下载流程拆成了三层第一层是指定仓库地址也就是repo_id第二层是选择仓库类型和版本比如分支、tag、commit 哈希第三层是对文件做范围筛选用--include和--exclude来决定只要哪些文件。三层参数加起来基本覆盖了各种下载场景而且逻辑非常统一。官方给了一个很重要的原则优先使用一个本地目录直接存放下载内容而不是先扔进缓存再拼接符号链接。这样一来你下载完看到的东西就是模型原始目录结构拿去部署、推理都省心。2. 装机与环境准备装对版本才不踩坑2.1 安装与版本检查先用最简单的方式安装新版本库。这里要注意hf命令不是单独安装的它来自huggingface_hub这个 Python 包。安装命令是pip install -U huggingface_hub如果你需要命令行补全、上传等功能可以装成带 CLI 扩展的版本不过绝大多数场景下上面的命令已经足够了。装完以后先用命令确认版本号确保你用的是新版而不是某个老掉牙的版本hf --version正常情况下这条命令会输出类似hf 0.29.0之类的信息。如果提示找不到hf说明你的huggingface_hub版本太旧或者当前 Python 环境的 PATH 没对上。你可以使用python -m huggingface_hub来验证是不是环境变量的锅。对于 2026 年的环境我建议直接把huggingface_hub升级到最新版别想着兼容老版本老版本很多参数已经悄悄改掉了。还顺便说一句如果你的机器上有多个 Python 环境比如 conda 环境或者系统的 Python 3.10一定要确保pip install和hf --version指向的是同一个环境。我踩过最典型的坑就是在 base 环境里装了包结果在虚拟环境里敲hf系统提示找不到命令。这种低级问题排查起来还挺折腾直接用which hf或where hf看路径最靠谱。2.2 登录鉴权识别私有模型和 gated 模型很多热门模型并不是点击就能下载的。比如 LLaMA 系列、某些商业授权模型都属于 gated 模型你必须先在官网页面上申请权限等审核通过之后才能下载。对于私有仓库更需要提供有效的 Access Token。旧版命令里你经常需要修改~/.huggingface/token或者手动传参新版hf在鉴权上做得更顺手了。你可以在浏览器里访问个人主页的 Settings → Access Tokens创建一个读取权限的 token。然后在命令行里执行hf auth login按提示粘贴 token 即可。完成之后token 会被保存到本地配置中后续下载 gated 模型都不用再重复登录。还有另一种临时做法就是每条命令后面直接带 token 参数hf download meta-llama/Llama-2-7b-chat-hf --token hf_xxxx不过我不推荐你把这个方法写进脚本因为 token 会留在 shell 历史记录里有泄露风险。更稳妥的做法是利用环境变量export HF_TOKENhf_xxxx然后正常执行hf download命令行工具会自动读取这个环境变量。这个方法对 CI/CD 和服务器部署都很友好也不容易误把 token 提交到代码仓库里。需要强调的是如果你使用 gated 模型并报出 401 或 403不要怀疑命令写错了先去检查两个东西第一你的账号是否已经在模型页面点了“同意条款”并审核通过第二你使用的 token 是否确实有权限。很多人在模型页面看到“Access”状态是 pending以为下载等一等就行实际上审核可能卡很久。你可以在官方页面的模型详情里重新申请一下也可以在 README 里看具体的授权规则。3. 实操上手模型 / 数据集 / Space / 代码仓库一次讲完3.1 模型下载默认参数怎么用先看最简单的用法。如果你想下载一个大模型到本地目录命令如下hf download gpt2 --local-dir ./models/gpt2这个命令会把gpt2仓库里的所有文件都下载到./models/gpt2目录下。你不需要手工创建目录工具会自己建。默认情况下下载完成后目录里就是模型配置文件、模型权重、tokenizer 文件等结构跟仓库保持一致。有的读者可能会问为什么不用--local_dir而是--local-dir这确实是一个值得注意的变更点。新命令的--local-dir参数是带短划线风格的旧版写下划线写错一个符号命令就会报错或者静默忽略。我的建议是在新版本里认准--local-dir同时记住--cache-dir也是短划线风格避免混用。对于超大模型官方和社区经常会采用分片存储比如把权重拆成model-00001-of-00010.safetensors等。hf download会自动处理这些分片文件你不用管它。它会依次创建pytorch_model-00001-of-00007.bin之类的文件推理框架会通过index.json或其他配置文件找到各分片。很多人一开始不放心担心文件不完整其实你可以在下载完成后用目录里的.complete文件或校验哈希来判断是否完整。新版工具在下载任务结束后会有一个最终状态输出看到Finished字样基本就是稳的。3.2 数据集下载repo-type 参数才是关键Hugging Face 上不仅模型多数据集也超级丰富。很多人栽在数据集下载上是因为默认的仓库类型是model不写--repo-type dataset它就把数据集当成模型仓库去解析自然报错。正确命令是hf download databricks/dolly-v2-12b --repo-type dataset --local-dir ./dolly-data这个命令会下载整个数据集仓库中的所有内容包括数据文件、数据处理脚本、README 等。实际使用中我通常不会一整个数据集全部拉下来更常见的是只下载某个配置文件对应的数据分片。这时候可以用上版本和过滤参数hf download imdb --repo-type dataset --revision main --include *.parquet --local-dir ./imdb-data这样就能只保留 parquet 格式的数据文件避免下载一堆没用的 lock 文件和脚本。对于超大数据集比如动辄几十 GB 的语料强烈建议先用浏览器或网页 API 看清楚目录结构想清楚需要哪些文件然后再命令下载。别一上来就整个仓库拉全量不然磁盘和带宽都会很痛。顺便提一句很多人会问“如何从 huggging face 下载数据集”其实最省事的方案就是命令行。浏览器网页只能单文件保存即使你点了“Download”浏览器也没办法处理海量小文件。命令行工具不仅能并发下载还能断点续传这是网页端完全比不了的。3.3 下载 Space 或代码仓库除了模型和目标数据用户还经常需要下载 Space 仓库。Space 是 Hugging Face 上用来托管 Gradio、Streamlit 等应用的环境里面通常包含app.py、requirements.txt、配置文件等。下载方法只是在命令里加一个--repo-type spacehf download chenchi0/FontDiffuser --repo-type space --local-dir ./fontdiffuser-spaceFontDiffuser 是字体生成领域的知名项目如果你平时关注中文字体生成方向的模型和应用这个 Space 仓库里会有不少可直接参考的推理脚本和界面代码。把它整个下载下来你就能在本地快速运行或改进项目。如果你要下载纯代码仓库同样使用--repo-type space或者其他仓库类型都能应对关键还是看仓库到底是什么类型。有时候你在网页上看到的模型仓库里也混着不少代码文件例如推理脚本、训练脚本、数据处理脚本这些默认都会被一起下载。如果你只想下载其中的代码而不是权重可以结合--exclude把权重文件排除掉hf download gpt2 --local-dir ./gpt2-code --exclude *.safetensors *.bin *.h5这样拿到的就是一个相对干净的代码目录适合看实现细节或做二次开发。4. 生产环境进阶镜像端点、文件过滤、并发与断点续传4.1 镜像端点和环境变量配置国内用户在下载大模型时经常遇到网络问题。这里说的不是本地网络故障而是 Hugging Face 的官方下载服务器在国内访问速度很飘甚至可能连不上。官方其实没有提供“内置加速”参数但社区早就给出了通用的环境变量方案HF_ENDPOINT。你可以在命令行里设置镜像端点export HF_ENDPOINThttps://hf-mirror.com然后在同一终端执行hf download。如果你用的是 Windows PowerShell可以用$env:HF_ENDPOINThttps://hf-mirror.com设置之后下载请求会走镜像站点很多情况下速度能明显提上来至少比直连官方服务器要稳定。需要注意的一点是HF_ENDPOINT是面向所有 Hugging Face 工具链的环境变量它不只对hf工具生效对你在 Python 代码里调用from_pretrained之类的函数同样有效。因此在服务器端我更推荐把它写进配置文件或者启动脚本而不是每次临时 export。我曾经因为忘记加这个环境变量在一个海外服务器上反复下载失败日志里全是连接超时。加上HF_ENDPOINT之后几秒钟就跑满带宽。对于长期运行的训练任务这是性价比最高的优化方式。4.2 include/exclude 与文件过滤如果你对仓库结构比较熟悉文件过滤能帮你省下大量时间和磁盘空间。--include和--exclude接受的是通配符模式可以写多个。实际使用中我最常用的组合是这样hf download bigscience/bloom-7b1 --local-dir ./bloom --include *.safetensors *.txt *.json这条命令只下载权重、说明文档和配置文件不下载其他临时脚本。反过来如果想排除某个大文件hf download bigscience/bloom-7b1 --local-dir ./bloom --exclude *.bin通配符的规则是 Unix glob 风格*可以匹配当前层级任意字符**可以递归匹配多个层级。需要注意的是shell 会自己处理通配符如果你忘记加引号某些情况下命令可能直接由 shell 展开成多个文件路径导致参数变成一堆奇怪的文件名。所以最好养成给模式加引号的好习惯。我看过不少人每次下载都用--local-dir并默认全量下载遇到那种仓库里既有几 GB 的权重文件、又有好几个 GB 视频演示文件的模型全量下载简直是灾难。先通过网页看一遍目录再用 include/exclude 精准拿文件这才是生产环境该有的操作方式。4.3 缓存、并发与断点续传的底层逻辑hf download默认会先把文件下载到缓存目录然后再复制或链接到--local-dir。这个缓存的默认位置在~/.cache/huggingface/hub也可以使用HF_HOME环境变量来修改。这样设计的好处是多个项目之间可以共享同一个缓存避免重复下载同一个模型多次。不过在磁盘空间紧张或者你只想要一个自包含目录时缓存会让目录变大不少。2026 年的新版本提供了参数来控制是否使用符号链接但我还是建议最省心的方式直接用--local-dir把它当作最终目标。如果你不想让缓存目录占太多空间可以在下载前把HF_HOME设置到临时目录export HF_HOME/tmp/hf-cache hf download gpt2 --local-dir ./models/gpt2下载大文件最怕的就是中断。hf download底层其实支持断点续传当你再次执行同一个下载命令时它默认会检查本地已有的文件大小只下载缺失的部分。这一块不需要额外加参数但我个人的经验是如果在下载过程中你想换镜像端点最好把已经下载到一半的目录清掉重下。因为你切换了端点之后文件来源不一致续传逻辑可能会出现无法解释的校验错误。并发方面工具本身已经支持多线程下载。对于包含大量小文件的数据集仓库并发效果很明显对于单个超大权重文件并发收益更多取决于服务端是否支持分片请求。你不需要刻意调并发数保持默认通常是最稳的。还有一个隐藏参数值得记住--force-download。当你因为本地目录损坏而要强制执行全量下载时加上这个参数会让工具忽略已有文件重新拉取。但谨慎使用别在正常续传时加它一不小心就把已经下载好的文件全重来一遍。5. 高频报错与修复清单5.1 Unknown repository / HTTP 401 / 403这是下载命令最经典的三类报错。Unknown repository意味着你写的仓库地址不存在或者仓库名拼错了。这时候你要去官网页面上确认一下repo_id的大小写和斜杠位置。HTTP 401 Unauthorized通常表示没有提供 token 或 token 无效。HTTP 403 Forbidden则多半是因为 gated 模型没有授权或者 token 权限不够。我自己的排查顺序是先看能不能在网页上正常访问仓库然后确认 token 有没有 read 权限最后确认是否申请了模型访问权限。如果全部没问题再考虑是不是网络中间层把认证头拦截了。这种情况下可以尝试把 token 通过HF_TOKEN环境变量传入不要依赖本地配置文件。5.2 网络超时、文件卡住、目录不完整下载到一半网络断开是跑下载任务最头疼的事。你重新执行命令它可能会显示Resuming download但也可能一直卡在一个字节都不动。出现这种情况我建议先做三件事第一用CtrlC终止当前任务然后看本地目录里有没有半截文件。第二切换HF_ENDPOINT把直连换成镜像端点很多情况下卡住就是直连服务器的连接被掐断了。第三删除刚才不完整的下载目录重新执行原始命令。虽然可能会丢掉一些已下载的分片但总比一直卡死强。有时候你会发现数据目录里文件数量对不上比如 index.json 里明明写了 12 个分片实际目录里只有 9 个。这大概率是中断时没有正常收尾。新版工具在下载异常时会留下.incomplete后缀文件检查到这类文件直接重跑命令就好。5.3 Windows 上不可忽视的小问题Windows 用户下载模型时还会碰到一些特有现象。最典型的是符号链接权限问题。hf download在 Windows 上为了创建本地链接可能需要管理员权限。如果你在普通控制台或者某些受限目录下运行可能会看到类似OSError或symbolic link privilege not held的报错。解决方式一是尽量把下载目标放到一个普通权限的目录比如用户目录下二是避免在系统盘中操作。如果你确实需要管理员权限那就用管理员身份打开终端。还有一个常见问题是路径长度超限。Windows 的路径最大长度限制比较保守下载某些目录层级很深的仓库时会出现找不到路径的诡异报错。这种情况可以直接设置环境变量$env:HF_HUB_DISABLE_SYMLINKS_WARNING1并尽量把--local-dir放在短路径下比如D:\models\llama2这种别藏在一长串目录里。这些细节看起来不起眼但在 Windows 服务器上跑批量下载时全踩一遍能把人逼疯。我在实际使用中还遇到过一个问题明明下载完成了from_pretrained却报本地文件缺失。后来检查发现是因为我只下了 model repo 里的权重文件没有把 tokenizer 和 config 文件一起下全。所以如果你准备离线使用一个模型强烈建议不看--include直接全量下载到目录再用from_pretrained加载时用本地路径。这样可以避免很多隐藏文件缺失的问题。拿不准的时候就全量拿磁盘够的情况下省事比省空间更重要。最后再分享一个我自己的下载习惯在大批量下载多个模型之前我会先写一个简单的清单文件把每个模型的repo_id、仓库类型、版本号、过滤规则都记录下来然后用 Bash 脚本循环执行hf download。这种模式特别适合要同时准备多个模型的线下推理环境。这样一套流程下来我基本已经不再打开浏览器手动点下载了所有模型和数据集都能用命令行一次性拿到本地。