Downloading datasets for offline use.

[eaubin]

I'd like to download datasets from HF and then run completely disconnected. I can do this by using file paths, but it's not ideal. I'd really like to use the repo_id and have it resolved locally when offline. Is there any way to do this? My failing workflow looks like:

export HF_HOME=/shared/huggingface
export HF_HUB_CACHE=/shared/huggingface/hub
export HF_DATASETS_CACHE=/shared/huggingface/datasets
export HF_TOKEN=...

uvx hf download TIGER-Lab/MMLU-Pro --repo-type dataset

# Remove network access.
export HF_HUB_OFFLINE=1
export HF_DATASETS_OFFLINE=1
python -c 'import datasets; datasets.load_dataset("TIGER-Lab/MMLU-Pro")'

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import datasets; datasets.load_dataset("TIGER-Lab/MMLU-Pro")
                     ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/mnt/llm-benchmark-validation/.venv/lib/python3.13/site-packages/datasets/load.py", line 1488, in load_dataset
    builder_instance = load_dataset_builder(
        path=path,
    ...<10 lines>...
        **config_kwargs,
    )
  File "/mnt/llm-benchmark-validation/.venv/lib/python3.13/site-packages/datasets/load.py", line 1133, in load_dataset_builder
    dataset_module = dataset_module_factory(
        path,
    ...<5 lines>...
        cache_dir=cache_dir,
    )
  File "/mnt/llm-benchmark-validation/.venv/lib/python3.13/site-packages/datasets/load.py", line 1032, in dataset_module_factory
    raise e1 from None
  File "/mnt/llm-benchmark-validation/.venv/lib/python3.13/site-packages/datasets/load.py", line 974, in dataset_module_factory
    raise ConnectionError(f"Couldn't reach '{path}' on the Hub ({e.__class__.__name__})") from e
ConnectionError: Couldn't reach 'TIGER-Lab/MMLU-Pro' on the Hub (OfflineModeIsEnabled)

[eaubin]

It seems that problem is that $HF_DATASETS_CACHE cannot be populated offline. If I load the dataset prior to removing network access it does not fail.

[KOKOSde]

hf download is only populating the Hub cache here. You need to call load_dataset(...) once while still online so the datasets cache gets built, then the same repo id should work offline.

[MOHD-OMER]

The fix is setting HF_DATASETS_OFFLINE=1 and making sure HF_HUB_CACHE points to where huggingface-cli download actually saves files. The issue is that load_dataset(repo_id) resolves through huggingface_hub cache (not HF_DATASETS_CACHE), so those two env vars need to align.

Here's the corrected workflow:

export HF_HOME=/shared/huggingface
export HF_HUB_CACHE=/shared/huggingface/hub   # this is where hf download saves
export HF_DATASETS_OFFLINE=1                  # key: tells datasets to not hit the network

# Download first (while online)
huggingface-cli download TIGER-Lab/MMLU-Pro --repo-type dataset

# Then offline, use load_dataset normally:
python -c "from datasets import load_dataset; ds = load_dataset('TIGER-Lab/MMLU-Pro')"

The critical env var is HF_DATASETS_OFFLINE=1 (not HF_DATASETS_CACHE). When set, load_dataset will look for the files in the hub cache and won't attempt any network calls. You can also set it in Python before importing:

import os
os.environ["HF_DATASETS_OFFLINE"] = "1"
from datasets import load_dataset
ds = load_dataset("TIGER-Lab/MMLU-Pro")

Docs reference: [https://huggingface.co/docs/datasets/en/cache#offline-mode](https://huggingface.co/docs/datasets/en/cache)

Verify the files are actually there

ls $HF_HUB_CACHE/datasets--TIGER-Lab--MMLU-Pro/

Should show snapshots/ folder

Also try passing the local path explicitly as fallback:

ds = load_dataset("parquet", data_files={"train": "/shared/huggingface/hub/datasets--TIGER-Lab--MMLU-Pro/snapshots//data/.parquet"})

[Hassanmahmood4]

hf download populates the Hub cache, but datasets.load_dataset() still appears to resolve the dataset script/metadata using the repo ID. In offline mode, that lookup can fail before the Hub cache is consulted.

One approach you could try is to “warm” the datasets cache while online:

from datasets import load_dataset
load_dataset("TIGER-Lab/MMLU-Pro")

This should prepare the dataset under HF_DATASETS_CACHE.

Then, after switching to:

export HF_HUB_OFFLINE=1
export HF_DATASETS_OFFLINE=1

try the same call again:

load_dataset("TIGER-Lab/MMLU-Pro")

If I understand the caching behavior correctly, this should allow the dataset to resolve from the local datasets cache without requiring network access.

If you only run:

hf download TIGER-Lab/MMLU-Pro --repo-type dataset

you’ll have the repository files in the Hub cache, but not necessarily the dataset builder state required by datasets.load_dataset() for offline use.

As a fallback, using the local path returned by hf download should also work. It would definitely be nice if repo IDs could resolve directly from the Hub cache in offline mode.

[VimalN2005]

Why This Happens

When you use hf download or huggingface-cli download, files are saved in the Hub snapshot cache format (/hub/datasets--<org>--<name>/snapshots/...).

Calling datasets.load_dataset("repo_id") invokes the dataset_module_factory, which attempts to fetch dataset metadata and scripts unless they have already been initialized in HF_DATASETS_CACHE.

---

Solution 1: Use snapshot_download to Resolve Local Path Offline (Cleanest)

Instead of relying on remote Hub name resolution offline, resolve the local snapshot directory:

import os
from huggingface_hub import snapshot_download
from datasets import load_dataset

# Resolve the cached snapshot directory locally without touching network
local_dir = snapshot_download(
    repo_id="TIGER-Lab/MMLU-Pro",
    repo_type="dataset",
    local_files_only=True
)

# Load directly from the local snapshot folder
dataset = load_dataset(local_dir)
print(dataset)

---

Solution 2: Pre-cache Properly Before Going Offline

If you want load_dataset("TIGER-Lab/MMLU-Pro") to work using the exact repo identifier offline, warm the cache by running load_dataset once while online:

# 1. While connected:
python -c 'import datasets; datasets.load_dataset("TIGER-Lab/MMLU-Pro")'

# 2. When offline:
export HF_DATASETS_OFFLINE=1
python -c 'import datasets; ds = datasets.load_dataset("TIGER-Lab/MMLU-Pro"); print(ds)'

Both methods prevent the ConnectionError (OfflineModeIsEnabled).

If this helps your offline workflow, please mark as accepted answer!