feat: honor HF_HUB_CACHE and propagate HF_HUB_OFFLINE into the container - #310
Open
thebroadercollective wants to merge 1 commit into
Open
feat: honor HF_HUB_CACHE and propagate HF_HUB_OFFLINE into the container#310thebroadercollective wants to merge 1 commit into
thebroadercollective wants to merge 1 commit into
Conversation
thebroadercollective
force-pushed
the
feat/hf-hub-cache-support
branch
from
July 31, 2026 00:44
a196099 to
be55078
Compare
This was referenced Sep 2, 2026
thebroadercollective
force-pushed
the
feat/hf-hub-cache-support
branch
4 times, most recently
from
September 9, 2026 02:29
9f5102d to
81f38ae
Compare
Resolve the HuggingFace hub cache the same way huggingface_hub does: HF_HUB_CACHE if set, else $HF_HOME/hub, with HF_HOME defaulting to $XDG_CACHE_HOME/huggingface (~/.cache/huggingface). HF_HOME and HF_HUB_CACHE are independent: HF_HOME holds tokens and other HF state, while HF_HUB_CACHE is specifically the model cache and may live elsewhere (e.g. a shared NFS mount). - hf-download.sh: HUB_PATH now honors HF_HUB_CACHE and XDG_CACHE_HOME. - run-recipe.py: check_model_exists() resolves the hub cache from the environment instead of hardcoding ~/.cache/huggingface/hub. - launch-cluster.sh: when HF_HUB_CACHE is set, bind-mount it over the container's hub location and set HF_HUB_CACHE in the container; both the cache dir and mount point are pre-created to avoid root-owned dirs. HF_HUB_OFFLINE is propagated from the host when set, since the cache is a host mount and the container should follow the host's offline intent.
thebroadercollective
force-pushed
the
feat/hf-hub-cache-support
branch
from
September 10, 2026 23:38
81f38ae to
0716da9
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Extends the
HF_HOMEsupport added for #68 to the rest of the HuggingFace cache environment variables, so the tooling resolves the model cache exactly the wayhuggingface_hubitself does:HF_HUB_CACHEif set, otherwise$HF_HOME/hub, withHF_HOMEdefaulting to$XDG_CACHE_HOME/huggingface(i.e.~/.cache/huggingface).Motivating use case: models stored on a NAS and exposed via an NFS mount that contains a standard HF hub cache hierarchy. Pointing
HF_HUB_CACHEat that mount (whileHF_HOME— tokens and other HF state — stays local) plusHF_HUB_OFFLINE=1now works end to end. This should also help with the workflows discussed in #153 / #247 for models that are already in an HF cache layout.Changes:
hf-download.sh:HUB_PATHhonorsHF_HUB_CACHE(andXDG_CACHE_HOMEin the fallback) instead of assuming$HF_HOME/hub.run-recipe.py:check_model_exists()resolves the hub cache from the environment instead of hardcoding~/.cache/huggingface/hub, so--setupno longer re-downloads models that are already present in a relocated cache.launch-cluster.sh:HF_HUB_CACHEis set, it is bind-mounted over the container's default hub location andHF_HUB_CACHEis set inside the container. The cache dir and the mount point are pre-created first so Docker doesn't create them root-owned.HF_HUB_OFFLINEis propagated from the host into the container when set — the HF cache is a host mount, so the container should follow the host's offline intent without needing manualCONTAINER_HF_HUB_OFFLINEconfiguration.Behavior is unchanged when none of these variables are set (
DOCKER_ARGSand all resolved paths are identical to currentmain).Notes / known limitations (both match the existing
HF_HOMEmount semantics):HF_HUB_CACHEmust be present at the same path on all cluster nodes, and like allDOCKER_ARGSit takes effect at container creation, so an already-running cluster needs a restart to pick it up. When the cache is a shared mount,hf-download.sh --copy-tois unnecessary (it would rsync the cache onto itself).Test plan
tests/test_recipes.shpasses (56/56) on the branchbash -n/py_compileclean on all three scriptsHUB_PATH/check_model_exists()resolution matrix:HF_HUB_CACHEset,HF_HOMEset,XDG_CACHE_HOMEset, and all unset (default unchanged)docker runargs: withHF_HUB_CACHE+HF_HUB_OFFLINE=1set, the hub mount and both env vars are added; with nothing set,DOCKER_ARGSis byte-identical tomainHF_HUB_OFFLINE=1(new path), and a run with no HF variables set against the local cache (no regression)