如何快速下载huggingface模型——全方法总结

Update:新版 hfd.sh 介绍，包括 -j多文件并行与--include/exclue。

Update: 推荐 huggingface 镜像站： hf-mirror 商业网/。

Update: 推荐官方的 huggingface-cli 命令行工具、以及HF-Mirror开发的 hfd脚本。

AI开发绕不过一个问题是，如何从hugging face下载模型/数据集，相关问题想必大家都没少搜过，方法五花八门，本人也曾在stackoverflow上回答过类似问题，然而很难见有文章将各类方法一次性讲全。

其实网络快、稳的话，随便哪种方法都挺好，然而国内网络问题，断点续传、多线程下载 等特性就显得尤为必要了，否则动辄断掉重来、下载速度慢，浪费生命！基于这个考虑，本文集成官方方法、第三方奇技淫巧，做了个总结排序，以飨读者：

（以下方法也适用于数据集下载）

方法类别		推荐程度	优点	缺点
基于URL	浏览器网页下载	⭐⭐⭐	通用性好	手动麻烦/无多线程
	多线程下载器(hfd/IDM等)	⭐⭐⭐⭐⭐	通用性好，鲁棒性好	手动麻烦
CLI工具	git clone命令	⭐⭐	简单	无断点续传/冗余文件/无多线程
专用CLI工具	huggingface-cli+hf_transfer	⭐⭐⭐	官方下载工具链，带加速功能	容错性低
	huggingface-cli	⭐⭐⭐⭐⭐	官方下载工具功能全	不支持多线程
Python方法	snapshot_download	⭐⭐⭐	官方支持，功能全	脚本复杂
	from_pretrained	⭐	官方支持，简单	不方便存储，功能不全
	hf_hub_download	⭐	官方支持	不支持全量下载/无多线程

本文对上述方法进行详细介绍，文末介绍几个常见问题：

• Q1: 如何下载 Llama 等需要登录的模型、数据集？
• Q2: 如何利用镜像站下载hf模型、数据集？
• Q3: 常见错误问答

1. 浏览器网页下载

模型项目页的 Files 栏中可以获取文件的下载链接。无需登录直接点击下载，还可以复制下载链接，用其他下载工具下载。这一点比国内某些又要注册登录，还不给出直链的平台，开放太多。

偶尔下载个模型，网页也挺方便

2. 多线程下载器

常规工具如浏览器默认采用单线程下载，由于国内网络运营商线路质量、QoS等因素有时候会很慢，多线程加速是一种有效、显著提高下载速度的方法。

经典多线程工具推荐两个：IDM、Aria2。 IDM 适用于 Windows、aria2 适用于 Linux/Mac OS。本文头图就是 IDM 工具。因此获取URL后，可以利用这些多线程工具来下载。以我的一次实测为例，单线程700KB/s，IDM 8线程 6MB/s。千兆宽带下，利用IDM能跑到80MB/s+。

然而，手动获取仓库中所有 URL 再去用 IDM 下载比较麻烦，因此我专门写了一个专用的多线程下载脚本 hfd，见如下介绍。

专用多线程下载器 hfd

hfd 是基于 curl 和 aria2 实现的专用于huggingface 下载的命令行脚本： hfd.sh（Gitst链接）。hfd 相比 huggingface-cli ，鲁棒性更好，很少会有奇奇怪怪的报错，此外多线程控制力度也更细，可以设置下载线程数、并行文件数。缺点是目前仅适用于 Linux 和 Mac OS。

其原理是 Step1：通过Hugging Face API获取模型/数据集仓库对应的所有文件 url；Step2：利用 aria2 多线程下载文件。

该工具同样支持设置镜像端点的环境变量:

export HF_ENDPOINT="https://hf-mirror.com"

基本命令：

./hfd.sh gpt2

如果没有安装 aria2，则可以改用 wget：

./hdf.sh bigscience/bloom-560m --tool wget

--include 指定下载特定文件

# Qwen2.5-Coder下载q2_k量化版本的模型
hfd Qwen/Qwen2.5-Coder-32B-Instruct-GGUF --include qwen2.5-coder-32b-instruct-q2_k.gguf
# gpt2下载onnx路径下的所有json文件
hfd gpt2 --include onnx/*.json 

--exclude 排除特定文件的下载

# gpt2仓库，不下载.bin格式的模型以及onnx模型
hfd gpt2 --exclude *.bin onnx/*

注意：语法方面，--include a --include b 和 --include a b 等价。

完整命令格式：

$ ./hfd.sh --help
用法:
  hfd <REPO_ID> [--include include_pattern1 include_pattern2 ...] [--exclude exclude_pattern1 exclude_pattern2 ...] [--hf_username username] [--hf_token token] [--tool aria2c|wget] [-x threads] [-j jobs] [--dataset] [--local-dir path]

描述:
使用提供的仓库ID从Hugging Face下载模型或数据集。

参数:
仓库ID          Hugging Face仓库ID(必需)
                格式:'组织名/仓库名'或旧版格式(如 gpt2)
选项:
包含/排除模式    用于匹配文件路径的模式,支持通配符。
                 例如:'--exclude *.safetensor .md', '--include vae/*'。
--include       (可选)指定要下载的文件包含模式(支持多个模式)。
--exclude       (可选)指定要排除下载的文件模式(支持多个模式)。
--hf_username   (可选)Hugging Face用户名用于认证(非邮箱)。
--hf_token      (可选)Hugging Face令牌用于认证。
--tool          (可选)使用的下载工具:aria2c(默认)或wget。
-x              (可选)aria2c的下载线程数(默认:4)。
-j              (可选)aria2c的并发下载数(默认:5)。
--dataset       (可选)标记下载的是数据集。
--local-dir     (可选)存储下载数据的目录路径。
                 默认下载到当前目录下以'仓库名'命名的子目录。(如果记仓库ID为'组织名/仓库名')。

示例:
hfd gpt2
hfd bigscience/bloom-560m --exclude *.bin .msgpack onnx/
hfd meta-llama/Llama-2-7b --hf_username myuser --hf_token mytoken -x 4
hfd lavita/medical-qa-shared-task-v1-toy --dataset

多线程和并行下载：

hfd 在使用 aria2c 作为下载工具时，支持两种并行配置：

• 单文件线程数 (-x)：控制每个文件的连接数，用法：hfd gpt2 -x 8，建议值：4-8，默认：4 线程。限制最大为10，别开太多了，服务器压力太大了😂。
• 并发文件数 (-j)：控制同时下载的文件数，用法：hfd gpt2 -j 3，建议值：3-8，默认：5 个文件。限制最大为10，同上别开太大。

组合使用：

hfd gpt2 -x 8 -j 3  # 每个文件 8 个线程，同时下载 3 个文件

3. Git clone

此外官方还提供了 git clone repo_url 的方式下载，这种方法相当简单，然而却是最不推荐直接用的方法，缺点有二：

• 1）不支持断点续传，断了重头再来；
• 2）clone 会下载历史版本占用磁盘空间，即使没有历史版本，.git文件夹大小也会存储一份当前版本模型的拷贝以及元信息，导致整个模型文件夹磁盘占用两倍以上，对于有些存在历史版本的模型，下载时间两倍以上，对于网络不够稳，磁盘不够大的用户，严重不推荐！

GIT_LFS_SKIP_SMUDGE可以clone时跳过大文件

一种比较好的实践是，设置 GIT_LFS_SKIP_SMUDGE=1 环境变量（这可能也是为什么官方huggingface页面提到这个参数的原因），再 git clone，这样 Git 会先下载仓库中除了大文件之外的文件。然后我们再用一些支持断点续传的工具来下载大文件，这样既支持了断点续传，.git 目录也不会太大（一般几百KB）。这整个流程，其实就是我上一节提到的 hfd 脚本的实现逻辑【更新：最新版hfd已弃用git clone过程以进一步提速，如对之前这个版本有需要的请看#507173】，感兴趣的可以参考/使用。

4. huggingface-cli+hf_transfer

huggingface-cli 和 hf_transfer 是 hugging face 官方提供的专门为下载而设计的工具链。前者是一个命令行工具，后者是下载加速模块。

4.1 huggingface-cli

huggingface-cli 隶属于 huggingface_hub 库，不仅可以下载模型、数据，还可以可以登录huggingface、上传模型、数据等。huggingface-cli 属于官方工具，其长期支持肯定是最好的。优先推荐！

安装依赖

pip install -U huggingface_hub

注意：huggingface_hub 依赖于 Python>=3.8，此外需要安装 0.17.0 及以上的版本，推荐0.19.0+。

基本用法-下载模型

huggingface-cli download bigscience/bloom-560m --local-dir bloom-560m

基本用法-下载数据集

huggingface-cli download --repo-type dataset lavita/medical-qa-shared-task-v1-toy

可选配置 export HF_HUB_DOWNLOAD_TIMEOUT=30

在网络不好的环境中，huggingface-cli 下载经常会报 timeout 超时错误，形如

HTTPSConnectionPool(host='cas-bridge.xethub.hf-mirror.com', port=443): Read timed out.

此时可以加 export HF_HUB_DOWNLOAD_TIMEOUT=30 延长超时时间，减少报错。

可选参数 --resume-download （已废弃）

【更新：huggingface_hub v0.23.0 已弃用 --resume-download参数，现在默认断点续传】

通过添加该参数，huggingface-cli的下载可断点续传，可以恢复上次因主动取消或网络波动异常退出的未完成的下载。

可选参数 --local-dir-use-symlinks False

【更新：请注意，v0.23.0开始加--local-dir 时会关闭符号链接】

值得注意的是，有个--local-dir-use-symlinks False 参数可选，因为huggingface的工具链默认会使用符号链接来存储下载的文件，导致--local-dir指定的目录中都是一些“链接文件”，真实模型则存储在~/.cache/huggingface下，如果不喜欢这个可以用 --local-dir-use-symlinks False取消这个逻辑。

但我不太喜欢取消这个参数，其最大方便点在于，调用时可以用模型名直接引用模型，而非指定模型路径。

什么意思呢？我们知道，from_pretrain 函数可以接收一个模型的id，也可以接收模型的存储路径。

假如我们用浏览器下载了一个模型，存储到服务器的 /data/gpt2 下了，调用的时候你得写模型的绝对路径

AutoModelForCausalLM.from_pretrained("/data/gpt2")

然而如果你用的 huggingface-cli download gpt2 下载，即使你把模型存储到了自己指定的目录，但是你仍然可以简单的用模型的名字来引用他。即：

AutoModelForCausalLM.from_pretrained("gpt2")

原理是因为huggingface工具链会在 .cache/huggingface/ 下维护一份模型的符号链接，无论你是否指定了模型的存储路径 ，缓存目录下都会链接过去，这样可以避免自己忘了自己曾经下过某个模型，此外调用的时候就很方便。

所以用了官方工具，既可以方便的用模型名引用模型，又可以自己把模型集中存在一个自定义的路径，方便管理。

当然，该工具目前还是有一些缺点的：

一是其存储逻辑不太直观，如上所属的缓存与链接逻辑，使得新手经常询问，模型究竟下载到哪里去了？

二是不支持单文件多线程。目前的行为是多文件并行，一次性会同时下载多个文件。

三是遇到网络中断会报错退出，不会自动重试，需要重新手动执行。【更新，v0.19.0已支持自动重试】

4.2 hf_transfer

hf_transfer 依附并兼容 huggingface-cli，是 hugging face 官方专门为提高下载速度基于 Rust 开发的一个模块，开启后在带宽充足的机器上可以跑到 500MB/s。本人实测了三台不同网络环境的机器，确实有黑科技啊，都把带宽跑满了（千兆）。

然而缺点是：

• 1. 没有进度条【更正，v0.19.0+开始支持进度条了】：是真的没有进度条，有进度条说明你没有开启成功。
• 2. 鲁棒性差，遇到网络不稳定会报错，并提示用户考虑关闭该模块提高容错性。可能这个模块还没有很成熟吧，对国内这种丢包率高的网络还是水土不服。

尽管如此，还是推荐给大家，看各自网络情况吧。

项目地址：https://github.com/huggingface/hf_transfer。

开启方法

(1)安装依赖

pip install -U hf-transfer

(2)设置 HF_HUB_ENABLE_HF_TRANSFER 环境变量为 1。

Linux

export HF_HUB_ENABLE_HF_TRANSFER=1

Windows Powershell

$env:HF_HUB_ENABLE_HF_TRANSFER = 1

开启后使用方法同 huggingface-cli：

huggingface-cli download --resume-download bigscience/bloom-560m --local-dir bloom-560m

注意：如果看到进度条，说明 hf_transfer 没开启成功！例如以下情况：

--resume-download 参数，指的是从上一次下载的地方继续，一般推荐总是加上该参数，断了方便继续。然而如果你一开始没有开启 hf_transfer，下载中途停掉并设置环境变量开启，此时用 --resume-download 会由于不兼容导致 hf_transfer 开启失败！总之观察是否有进度条就可以知道有没有开启成功，没有进度条就说明开启成功！

5. snapshot_download

huggingface 官方提供了snapshot_download 方法下载完整模型，参数众多、比较完善。相比下文另两个 python 方法，推荐 snapshot_download 方法来下载模型，支持断点续传、多线程、指定路径、配置代理、排除特定文件等功能。然而有两个缺点：

• 1)）该方法依赖于 transformers 库，而这个库是个开发用的库，对于自动化运维有点重；
• 2） 该方法调用比较复杂，参数较多，例如默认会检查用户缓存目录下是否已有对应模型，如已有则会创建符号链接，不理解的容易导致问题。外加需要配置代理。常见参数配置如下：

from huggingface_hub import snapshot_download
snapshot_download(
  repo_id="bigscience/bloom-560m",
  local_dir="/data/user/test",
  proxies={"https": "http://localhost:7890"},
  max_workers=8
)

对于需要登录的模型，还需要两行额外代码：

import huggingface_hub
huggingface_hub.login("HF_TOKEN") # token 从 https://huggingface.co/settings/tokens 获取

一般很难记住这么多代码，经常性要下载模型的，不如用上文介绍的官方的命令行工具 huggingface-cli 了。

6. from_pretrained

不过多介绍了。常规方法。

7. hf_hub_download

不过多介绍了。常规方法。

Q1:如何下载hf上需要登陆的模型?

由于模型发布者的版权的要求，部分模型无法公开访问下载，需要在 huggingface 上申请许可通过后，才可以下载。这类模型称之为 Gated Model。基本步骤是：

• 1.申请许可
• 2.获取 access token（用于命令行和python方法调用）
• 3.下载

申请许可

此步骤必须在 huggingface 官网注册登录后申请，由于网络安全原因，镜像站一般不支持。

申请后一般等待几分钟到几天不等（一般几分钟就行），会发邮件通知你审批结果。

获取 access token

申请通过后，就可以在模型主页的 Files and versions 中看到模型文件了，浏览器的话直接点击下载即可。但是如果想要用工具例如 huggingface-cli 下载，则需要获取 access token。

Access Token 获取地址：  huggingface co/settings/tokens

访问 huggingface 设置页面的 token 管理页，选择 New 一个 token，只需要 Read 权限即可，创建后便可以在工具中调用时使用了。

下载

除了登陆后浏览器直接下载，几种工具的使用方法分别介绍如下：

Git clone

https

git clone https://<hf_username>:<hf_token>@huggingface.co/meta-llama/Llama-2-7b-chat-hf

huggingface-cli： 添加 --token 参数

huggingface-cli download --token hf_*** --resume-download bigscience/bloom-560m --local-dir bloom-560m

curl, wget：在 header 中添加 token

curl -L --header "Authorization: Bearer hf_***" -o model-00001-of-00002.safetensors https://huggingface.co/meta-llama/Llama-2-7b-chat-hf/resolve/main/model-00001-of-00002.safetensors

wget --header "Authorization: Bearer hf_***" https://huggingface.co/meta-llama/Llama-2-7b-chat-hf/resolve/main/model-00001-of-00002.safetensors

snapshot_download：调用 login 方法

import huggingface_hub
huggingface_hub.login("hf_***")

Q2:如何利用镜像站下载hf模型/数据集?

直接访问镜像站，获取文件URL

镜像站  hf-mirror 商业网/。

设置 HF_ENDPOINT 环境变量

HF_ENDPOINT 该变量是 HF 相关库官方支持的一个环境变量，设置后，相关库会尊重该变量指定的主机名，替换 huggingface co 域名进行模型、数据集的下载和上传，从而做到无需修改python的transformers代码，即可利用上镜像站来加载模型。具体支持以下库：

• huggingface-cli
• snapshot_download
• from_pretrained
• hf_hub_download
• timm.create_model

设置方法

以下介绍各种环境下如何设置环境变量，以及如何将环境变量的配置命令写入到终端的配置文件中，使得终端自动加载该环境变量，免去每次手动执行命令的麻烦。

Linux/Mac OS

export HF_ENDPOINT="https://hf-mirror.com"

Linux 写入到~/.bashrc中：

echo 'export HF_ENDPOINT="https://hf-mirror.com"' >> ~/.bashrc

Mac OS 写入到 ~/.zshrc 中：

echo 'export HF_ENDPOINT="https://hf-mirror.com"' >> ~/.zshrc

Windows Powershell

$env:HF_ENDPOINT = "https://hf-mirror.com"

用以下命令写入到 ~\Documents\WindowsPowerShellMicrosoft.PowerShell_profile.ps1 中：

Add-Content -Path $PROFILE -Value '$env:HF_ENDPOINT = "https://hf-mirror.com"'

Python

import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

注意os.environ得在import huggingface库相关语句之前执行。

Q3:常见错误问答

Q3.1: huggingface-cli: error: invalid choice: 'download'

版本问题。huggingface-hub>=0.17.0 && Python>=3.8。

huggingface-cli 需安装 0.17.0 及以上的版本才支持download子命令，但如果你pip显示的可安装的最新版本都低于0.17.0，可能是你的Python版本没有达到huggingface_hub要求的3.8+的要求（huggingface co/docs/huggingface_hub/main/en/installation）。

Q3.2: Error downloading ... https://cdn-lfs.huggingface.co/xxx...

报错中有出现 huggingface co 这个域名的，多半是因为没有正确设置镜像断点环境变量，导致走的仍然是hf官方服务器出现的网络错误。请正确设置 HF_ENDPOINT，具体设置看Q2。

Q3.3: HTTPSConnectionPool(host='cas-bridge.xethub.hf-mirror.com', port=443): Read timed out.

该错误是使用huggingface-cli 会产生的报错，因为下载连接服务器的默认超时时间是10秒，然而服务器有时响应较慢，会导致报该超时错误，官方文档提示可以设置以下环境变量延长超时时间，从而减少该错误的发生

export HF_HUB_DOWNLOAD_TIMEOUT=30

如上会将超时时间设置为30秒。

Q3.4: 429 错误

有两种可能：

情况一：浏览器访问提示429错误。如果不在下载模型，只是浏览hf网站或者镜像站时，这种一般是网站浏览频率过大， 可多次刷新尝试。

情况二：命令行工具下载提示429错误。429 Client Error: Too Many Requests 特别是下载一些小文件特别多的数据集的时候，很容易触发，原因是hf源站对于非登录用户的访问频率有较为严格的限制。如果登录后，频率可提高一倍。例如对于huggingface-cli 请传递 --token 参数，对于 hfd 请传递 hf_token 参数。

Hugging Face源站对于用户的具体访问频率限制可以参见官方这篇文档：

Hub Rate limitshf-mirror.com/docs/hub/rate-limits（hf-mirror 商业网/docs/hub/rate-limits）

总结

以上，我们介绍了浏览器、多线程工具、git clone、huggingface-cli、hf_transfer、python方法、hfd脚本等众多方法，各自有其适用场景，大家根据自己的操作系统的支持情况以及个人习惯来选择。

个人推荐：

• Linux/Mac OS/windows 默认推荐使用huggingface-cli。
• 网络连接不好，推荐使用第三方、成熟的多线程下载工具，Linux 和 Mac OS 推荐hfd脚本+aria2c，Windows 推荐 IDM。用第三方工具的好处是，下载上百GB的模型、数据集，你可以放个一晚上，第二天就下载好了，而不是第二天早晨发现下载了10%断了还得继续。
• 偶尔少量文件下载，直接访问镜像站，用浏览器下载。