DataCrosslane
提交需求
提交需求
首页/实用指南/科研数据

Hugging Face 数据集怎么下载？国内下载慢时的几种方法

Hugging Face 上的公开数据集可以使用官方 hf 命令下载。国内连接较慢时，可以切换 HF-Mirror；本文直接给出完整命令和常见问题处理方式。

1. 安装 Hugging Face CLI

尚未安装 Python 时，先参考 Python 3 安装与 pip 镜像配置。

Windows

powershell
python -m pip install -U huggingface_hub

macOS / Linux

bash
python3 -m pip install -U huggingface_hub

安装完成后检查：

bash
hf --help

2. 下载整个数据集

假设数据集地址是：

text
https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k

数据集 ID 是 HuggingFaceH4/ultrachat_200k。

bash
hf download HuggingFaceH4/ultrachat_200k \
  --repo-type dataset \
  --local-dir ./ultrachat_200k

Windows PowerShell

powershell
hf download HuggingFaceH4/ultrachat_200k --repo-type dataset --local-dir ./ultrachat_200k

3. 只下载指定文件

bash
hf download OWNER/DATASET \
  data/train.parquet \
  --repo-type dataset \
  --local-dir ./dataset

下载多个文件：

bash
hf download OWNER/DATASET \
  data/train.parquet \
  data/test.parquet \
  --repo-type dataset \
  --local-dir ./dataset

只下载某一种文件：

bash
hf download OWNER/DATASET \
  --repo-type dataset \
  --include "*.parquet" \
  --local-dir ./dataset

排除某一种文件：

bash
hf download OWNER/DATASET \
  --repo-type dataset \
  --exclude "*.json" \
  --local-dir ./dataset

4. 国内下载慢：使用 HF-Mirror

HF-Mirror 是第三方 Hugging Face 镜像。

macOS / Linux

bash
export HF_ENDPOINT=https://hf-mirror.com
hf download OWNER/DATASET \
  --repo-type dataset \
  --local-dir ./dataset

只让当前这一次下载使用镜像：

bash
HF_ENDPOINT=https://hf-mirror.com \
hf download OWNER/DATASET \
  --repo-type dataset \
  --local-dir ./dataset

Windows PowerShell

powershell
$env:HF_ENDPOINT = "https://hf-mirror.com"
hf download OWNER/DATASET --repo-type dataset --local-dir ./dataset

恢复 Hugging Face 官方地址

bash
unset HF_ENDPOINT

Windows PowerShell：

powershell
Remove-Item Env:HF_ENDPOINT

5. 下载经常超时

macOS / Linux

bash
export HF_HUB_DOWNLOAD_TIMEOUT=30

Windows PowerShell

powershell
$env:HF_HUB_DOWNLOAD_TIMEOUT = "30"

仍然频繁超时时，可以提高到 60 秒：

bash
export HF_HUB_DOWNLOAD_TIMEOUT=60

6. 下载前查看文件和大小

bash
hf download OWNER/DATASET \
  --repo-type dataset \
  --dry-run

确认需要的文件后，再用 --include 或指定文件路径下载。

7. 需要登录或申请权限的数据集

先在 Hugging Face 对应 Dataset 页面完成访问申请，然后登录：

bash
hf auth login

授权完成后再执行正常的 hf download。

8. 常见报错

hf: command not found

重新安装 Hugging Face CLI，并重新打开终端：

bash
python3 -m pip install -U huggingface_hub
hf --help

401 / 403

先检查 Dataset 页面是否需要登录或申请访问权限，再执行：

bash
hf auth login

Repository Not Found

检查 Repo ID。网页地址为 https://huggingface.co/datasets/OWNER/DATASET 时，命令里填写 OWNER/DATASET。

Read timed out

bash
export HF_HUB_DOWNLOAD_TIMEOUT=60

9. 一个完整例子

bash
export HF_ENDPOINT=https://hf-mirror.com
hf download HuggingFaceH4/ultrachat_200k \
  --repo-type dataset \
  --local-dir ./ultrachat_200k

下载仍不稳定时

如果数据集页面可以访问，但通过官方 CLI 或镜像仍无法正常获取，可以将 Hugging Face 数据集链接和需要的文件范围提交给 DataCrosslane 确认。

不需要提供 Hugging Face 主账号密码。