The Hub cache and pushing your own model

Setup#

pip install transformers huggingface_hub

Tested with transformers 5.6 and huggingface_hub 1.12. The tour downloads sshleifer/tiny-gpt2 — about 4.7 MB of files, small enough to be painless.

Where the files land#

import os
os.environ["HF_HOME"] = os.path.abspath("demo_cache")   # keeps this demo out of your real cache

from huggingface_hub import snapshot_download, scan_cache_dir

path = snapshot_download("sshleifer/tiny-gpt2")
print("repo folder:", os.path.basename(os.path.dirname(os.path.dirname(path))))
print("commit:", os.path.basename(path)[:12], "...")

info = scan_cache_dir()
for repo in info.repos:
    print(f"{repo.repo_id:22} {repo.size_on_disk_str:>8}  revisions={len(repo.revisions)}")
print("total on disk:", info.size_on_disk_str)

repo folder: models--sshleifer--tiny-gpt2
commit: 5f91d94bd9cd ...
sshleifer/tiny-gpt2        4.7M  revisions=1
total on disk: 4.7M

The commit hash differs if the repository has been updated since this was written. The folder name does not.

Inside that repo folder are three parts:

models--sshleifer--tiny-gpt2/
├── blobs/       file contents, each named by its hash
├── refs/main    which commit "main" currently points at
└── snapshots/<commit>/config.json → ../../blobs/<hash>

snapshots/<commit>/ looks like a normal folder of files, but its entries point into the blobs/ store. Download two commits of the same model and unchanged files are stored once, not twice.

Saving your own model#

import os
from transformers import AutoModelForSequenceClassification, AutoTokenizer

NAME = "google/bert_uncased_L-2_H-128_A-2"        # BERT-tiny, about 18 MB of files
model = AutoModelForSequenceClassification.from_pretrained(NAME, num_labels=2)
tok = AutoTokenizer.from_pretrained(NAME)

# label names travel with the model, so nobody downstream has to guess what "1" means
model.config.id2label = {0: "NEGATIVE", 1: "POSITIVE"}
model.config.label2id = {"NEGATIVE": 0, "POSITIVE": 1}

model.save_pretrained("my-review-model")
tok.save_pretrained("my-review-model")

for f in sorted(os.listdir("my-review-model")):
    print(f"{f:24} {os.path.getsize(os.path.join('my-review-model', f)):>9,} bytes")

config.json                    842 bytes
model.safetensors        17,549,312 bytes
tokenizer.json             711,396 bytes
tokenizer_config.json          394 bytes

That model still has a freshly randomised head, so its numbers are noise — see which AutoModel class to use. Train it with the Trainer API before sharing anything.

The walkthrough#

from_pretrained accepts a folder anywhere. AutoModelForSequenceClassification.from_pretrained("my-review-model") reads that folder with no Hub involved. A repo id and a local path are interchangeable everywhere in the library.

Four files is the whole model. config.json describes the architecture, model.safetensors holds the weights, and the two tokenizer files describe the text side. Nothing else is needed to reload it on another machine.

Pushing needs an account and a token. Create one under Settings → Access Tokens on huggingface.co with write permission, then run hf auth login in your terminal and paste it. After that:

model.push_to_hub("your-username/my-review-model", private=True)
tok.push_to_hub("your-username/my-review-model")

That creates the repository if it does not exist and uploads the same four files. No output block here — it writes to your account, not one we can show. Start with private=True and open it up once you are happy.

A model page without a description is close to useless. Write a README.md in the folder covering training data, intended use, and known failures before pushing. Model cards covers what belongs in one.

Pin the version when results matter. from_pretrained(NAME, revision="a1b2c3d") loads one exact commit forever. Without it, main moving under you changes your results with no warning and no error.

Common mistakes#

Filling the disk without noticing. The cache never shrinks on its own. A few months of experiments becomes tens of gigabytes. Check it with hf cache scan:

REPO ID                              REPO TYPE SIZE ON DISK NB FILES LAST_ACCESSED  REFS
------------------------------------ --------- ------------ -------- -------------- ----
google/bert_uncased_L-2_H-128_A-2    model            18.0M        4 20 seconds ago main
sshleifer/tiny-gpt2                  model             4.7M        9 8 minutes ago  main

Done in 0.0s. Scanned 2 repo(s) for a total of 22.7M.

The real table also prints LAST_MODIFIED and a very wide LOCAL PATH column; both are cut above so the table fits this page. Then hf cache delete opens a picker for the revisions you no longer need. This command was huggingface-cli scan-cache before huggingface_hub 1.0, and plenty of older tutorials still say so.

Deleting cache files by hand while a script runs. Downloads take lock files under .locks/. Removing files mid-download leaves a half-written blob that reloads as a corrupt-weights error. Use the hf cache commands instead.

Moving the cache without telling the library. On a laptop with a small system drive, point HF_HOME at a bigger disk — as an environment variable, set before any import. Setting it after transformers is imported changes nothing, because the path was already read.

Pushing a folder full of checkpoints. Trainer output directories carry optimizer state worth several times the model. Push the save_pretrained folder, not the training directory.

Assuming downloads work offline. With HF_HUB_OFFLINE=1, cached models load and uncached ones raise an error instead of hanging. Set it on machines with no internet, so failures arrive immediately and readably.

Try it yourself#

Download hf-internal-testing/tiny-random-gpt2 (under 0.5 MB) into the same demo cache, then run scan_cache_dir() again and read the new total. Now load that model twice in one script and time both loads. The gap between them is what the cache buys you.

What to learn next#

• The Datasets library — the same Hub, holding data instead of weights.
• Model cards — what to write before anything goes public.
• Hugging Face — the ecosystem tour, if you arrived here sideways.