# How Transformers Handles Model Hub Caching and Offline Loading

> Learn how Hugging Face Transformers handles model hub caching and offline loading. Discover seamless local cache checks and efficient downloads or error handling for offline use.

- Repository: [Hugging Face/transformers](https://github.com/huggingface/transformers)
- Tags: internals
- Published: 2026-02-22

---

**When you call `from_pretrained`, the library first checks the local cache at `~/.cache/huggingface/hub`; if the file exists it returns immediately, otherwise it downloads from the Hub unless offline mode is active, in which case it raises a clear error or falls back to cached files.**

The Hugging Face Transformers library implements a robust two-tier system for model hub caching and offline loading that ensures reproducible, air-gapped deployments. Every call to `AutoModel.from_pretrained`, `AutoTokenizer`, or `cached_file` ultimately routes through [`src/transformers/utils/hub.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/hub.py), where the library decides whether to read from disk or fetch from the network.

## Cache Architecture and Directory Layout

The cache root is determined by environment variables and constants defined in the codebase. By default, files live in `~/.cache/huggingface/hub`, controlled by `constants.HF_HUB_CACHE` and overridable via `HF_HOME` or `HF_MODULES_CACHE`.

In [`src/transformers/utils/hub.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/hub.py) (lines 87‑93), the library resolves the cache directory:

```python

# From hub.py L87-L93

cache_dir = os.environ.get("HF_HOME", os.path.expanduser("~/.cache/huggingface"))
cache_dir = os.path.join(cache_dir, "hub")

```

The on-disk layout mirrors the Hub repository structure:

```

~/.cache/huggingface/hub/
├─ models--<repo_id>/
│   ├─ snapshots/
│   │   └─ <revision_hash>/
│   │       ├─ pytorch_model.bin
│   │       ├─ config.json
│   │       └─ …
└─ <repo_type>/

```

This design allows `try_to_load_from_cache` (hub.py lines 100‑108) to locate files using only the repo id, filename, and revision hash.

## The Caching Pipeline

Every file fetch follows a strict resolution order implemented in `cached_files` ([`src/transformers/utils/hub.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/hub.py), lines 10‑33 and 47‑108):

1. **Local directory check** – If `path_or_repo_id` points to a local path, it is used directly (lines 70‑86).
2. **Cache lookup** – `try_to_load_from_cache` checks whether the exact revision already exists in `snapshots/` (lines 94‑110).
3. **Offline guard** – `is_offline_mode()` (line 361‑364) forces `local_files_only=True` when `HF_HUB_OFFLINE` or `TRANSFORMERS_OFFLINE` is set, skipping any network call.
4. **Network download** – If allowed, `hf_hub_download` (single file) or `snapshot_download` (full repo) writes directly into the cache folder (lines 18‑28).
5. **Return resolved path** – The final list of local paths is returned to the caller.

Error handling (lines 121‑128) produces descriptive `OSError` messages when a file is missing in offline mode, telling users exactly which file is required and how to pre-download it.

## Offline Mode Implementation

Offline behavior is controlled by two environment variables checked in `is_offline_mode()`:

- `HF_HUB_OFFLINE` – Modern, preferred switch.
- `TRANSFORMERS_OFFLINE` – Legacy alias for backward compatibility.

Both accept truthy values (`"1"`, `"true"`, `"yes"`). When active, the library automatically sets `local_files_only=True` in `cached_files` (hub.py lines 361‑364), ensuring that `hf_hub_download` is never invoked.

You can also trigger local-only behavior per-call without setting environment variables:

```python
from transformers import AutoModel

model = AutoModel.from_pretrained(
    "google-bert/bert-base-uncased",
    local_files_only=True,
)

```

## Practical Usage Examples

### Loading a model with automatic caching

```python
from transformers import AutoModel

# First call downloads to ~/.cache/huggingface/hub

model = AutoModel.from_pretrained("google-bert/bert-base-uncased")

# Subsequent calls read from disk instantly

model = AutoModel.from_pretrained("google-bert/bert-base-uncased")

```

### Enabling global offline mode

```bash
export HF_HUB_OFFLINE=1

# or

export TRANSFORMERS_OFFLINE=1

```

```python
from transformers import AutoTokenizer

# Raises OSError if files are not already cached

tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased")

```

### Inspecting cache contents programmatically

```python
from huggingface_hub import snapshot_download

# Returns the local path inside the cache

cache_path = snapshot_download(
    "google-bert/bert-base-uncased",
    local_files_only=True,
)
print(cache_path)

# Output: /home/user/.cache/huggingface/hub/models--google-bert--bert-base-uncased/snapshots/<hash>

```

### Using cached_file directly

```python
from transformers.utils.hub import cached_file

config_path = cached_file(
    "google-bert/bert-base-uncased",
    "config.json",
    revision="main",
)
print(config_path)  # None if not cached and not in offline mode

```

## Key Source Files

| File | Role |
|------|------|
| [`src/transformers/utils/hub.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/hub.py) | Central implementation of `cached_files`, `cached_file`, `try_to_load_from_cache`, and offline-mode guards. |
| [`src/transformers/modeling_utils.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/modeling_utils.py) | Uses `is_offline_mode` to protect weight-loading logic in `from_pretrained`. |
| [`src/transformers/tokenization_utils_tokenizers.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/tokenization_utils_tokenizers.py) | Applies offline guards when fetching tokenizer files. |
| [`src/transformers/processing_utils.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/processing_utils.py) | Implements offline checks for image and feature-extraction assets. |
| [`src/transformers/video_processing_utils.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/video_processing_utils.py) | Shows offline guards for video-related processing files. |
| [`tests/utils/test_offline.py`](https://github.com/huggingface/transformers/blob/main/tests/utils/test_offline.py) | Test suite verifying offline behavior and environment-variable handling. |

## Summary

- The Transformers library stores all downloaded artifacts in `~/.cache/huggingface/hub` (configurable via `HF_HOME`), using a structured layout that maps repo IDs to snapshot folders.
- **Offline mode** is triggered by `HF_HUB_OFFLINE` or `TRANSFORMERS_OFFLINE`, forcing `local_files_only=True` and preventing any HTTP requests.
- The `cached_files` function in [`src/transformers/utils/hub.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/hub.py) orchestrates the resolution order: local path → cache lookup → (optional) download → error handling.
- Users can force cache-only behavior per-call with `local_files_only=True`, or inspect cache contents using `huggingface_hub.snapshot_download`.

## Frequently Asked Questions

### How do I completely disable network access in Transformers?

Set the environment variable `HF_HUB_OFFLINE=1` (or the legacy `TRANSFORMERS_OFFLINE=1`) before importing the library. This forces every `from_pretrained` call to read only from the local cache at `~/.cache/huggingface/hub` and raises a clear error if files are missing.

### Where does Transformers store downloaded models?

By default, files live in `~/.cache/huggingface/hub`. You can change this by setting the `HF_HOME` environment variable; the library appends `hub` to that path. The internal layout uses `models--<repo_id>/snapshots/<revision_hash>/` to keep different versions isolated.

### What happens if a file is missing while in offline mode?

The library raises an `OSError` with a descriptive message indicating exactly which file is required and suggesting that you download it while online first. This error originates in the exception handling block of `cached_files` in [`src/transformers/utils/hub.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/hub.py) (lines 121‑128).

### Can I use a specific revision or commit hash when loading offline?

Yes. When you specify `revision="abc123"` in `from_pretrained`, the cache lookup in `try_to_load_from_cache` searches for a snapshot folder matching that exact hash. As long as you previously downloaded that revision while online, offline loading will succeed.