From 70d2489af6166e4f2e1ff8b9e017e653abfb7c88 Mon Sep 17 00:00:00 2001 From: stevhliu Date: Fri, 18 Sep 2026 10:13:06 -0700 Subject: [PATCH 1/2] cache/commit --- docs/source/en/installation.md | 6 +++++- docs/source/en/model_sharing.md | 4 ++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/source/en/installation.md b/docs/source/en/installation.md index ef9a278efc74..5c110e6e4fa4 100644 --- a/docs/source/en/installation.md +++ b/docs/source/en/installation.md @@ -168,7 +168,9 @@ After installation, you can configure the Transformers cache location or set up When you load a pretrained model with [`~PreTrainedModel.from_pretrained`], the model is downloaded from the Hub and locally cached. -Every time you load a model, it checks whether the cached model is up-to-date. If it's the same, then the local model is loaded. If it's not the same, the newer model is downloaded and cached. +If you pass a commit hash, Transformers uses the local cache for that commit's files and does not re-check the Hub for each one (including files that are known to be missing). + +If you pass a branch or tag, Transformers contacts the Hub once at the start of the load to pick the commit, then uses the cache the same way for that commit's files. The default directory given by the shell environment variable `HF_HUB_CACHE` is `~/.cache/huggingface/hub`. On Windows, the default directory is `C:\Users\username\.cache\huggingface\hub`. @@ -205,3 +207,5 @@ from transformers import LlamaForCausalLM model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True) ``` + +Offline mode (or `local_files_only=True`) can still turn a branch or tag into a commit if an earlier online load saved that mapping in the cache. If the mapping was never saved, Transformers keeps the branch or tag you asked for and continues with the regular offline load. You get the same cache hits or missing-file errors as a normal offline load. diff --git a/docs/source/en/model_sharing.md b/docs/source/en/model_sharing.md index ceef2b64c07e..495e57626ef0 100644 --- a/docs/source/en/model_sharing.md +++ b/docs/source/en/model_sharing.md @@ -63,6 +63,10 @@ model = AutoModel.from_pretrained( ) ``` +Loading from a branch or tag pins every file in that call to one commit, (when `revision` is omitted), then fetches every file from that commit. + +That pin lasts for the call only. For reproducibility across runs, pass an explicit commit hash or a tag you treat as fixed. Do not rely on `main` or another moving branch staying fixed between runs. + Model repositories also support [gating](https://hf.co/docs/hub/models-gated) to control who can access a model. Gating is common for allowing a select group of users to preview a research model before it's made public.
From d5d08685832850262d09cfef4075e980184f26df Mon Sep 17 00:00:00 2001 From: stevhliu Date: Wed, 23 Sep 2026 09:10:57 -0700 Subject: [PATCH 2/2] feedback --- docs/source/en/installation.md | 2 +- docs/source/en/model_sharing.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/en/installation.md b/docs/source/en/installation.md index 5c110e6e4fa4..ce2a4d046267 100644 --- a/docs/source/en/installation.md +++ b/docs/source/en/installation.md @@ -168,7 +168,7 @@ After installation, you can configure the Transformers cache location or set up When you load a pretrained model with [`~PreTrainedModel.from_pretrained`], the model is downloaded from the Hub and locally cached. -If you pass a commit hash, Transformers uses the local cache for that commit's files and does not re-check the Hub for each one (including files that are known to be missing). +If you pass a commit hash, Transformers uses the local cache for that commit's files and does not re-check the Hub for each one (including files that are known to be missing). This is the default behavior when no revision is specified. If you pass a branch or tag, Transformers contacts the Hub once at the start of the load to pick the commit, then uses the cache the same way for that commit's files. diff --git a/docs/source/en/model_sharing.md b/docs/source/en/model_sharing.md index 495e57626ef0..b17d1789df65 100644 --- a/docs/source/en/model_sharing.md +++ b/docs/source/en/model_sharing.md @@ -63,7 +63,7 @@ model = AutoModel.from_pretrained( ) ``` -Loading from a branch or tag pins every file in that call to one commit, (when `revision` is omitted), then fetches every file from that commit. +Loading from a branch or tag pins every file in that call to one commit, then fetches every file from that commit. That pin lasts for the call only. For reproducibility across runs, pass an explicit commit hash or a tag you treat as fixed. Do not rely on `main` or another moving branch staying fixed between runs.