Why a local model path still tries to reach HuggingFace, and how to load fully offline

By default, huggingface_hub and transformers try to reach the Hub first to check whether cached files are up to date (an ETag/metadata check), only falling back to local cache after that attempt times out or fails, which can be slow and, in a fully air-gapped network with no DNS resolution at all, can hang or fail hard rather than falling back gracefully. Explicit offline mode skips this network check entirely and goes straight to local files.

Fix: Export HF_HUB_OFFLINE=1 and TRANSFORMERS_OFFLINE=1 in the environment before any Python process starts, or set them programmatically at the very top of your script before importing transformers.

export HF_HUB_OFFLINE=1
export TRANSFORMERS_OFFLINE=1

It is common to manually copy only the large weight files (.safetensors) to an air-gapped target while forgetting smaller companion files like config.json, tokenizer.json, tokenizer_config.json, special_tokens_map.json, or generation_config.json. When any of these is missing, transformers falls back to trying to fetch it remotely, which fails hard with no network available.

Fix: Always transfer the complete snapshot_download output directory (or use huggingface-cli download --local-dir to get one deliberately), not a hand-picked subset of files, so every file the loader might need is present locally.

huggingface-cli download org/model --local-dir ./model-snapshot

Models using trust_remote_code often have an auto_map field in their config that maps class names to a module path within their original HuggingFace repo. Even with the weights fully local, loading such a model with trust_remote_code=True can still trigger a fetch of that referenced Python module from the remote repo unless that code has also been fully localized.

Fix: For trust_remote_code models bound for an air-gapped environment, download the custom Python modeling files explicitly as part of the snapshot and verify the auto_map paths resolve locally, or vendor the code into your own package entirely to remove the dependency on remote resolution.

python -c "import json; print(json.load(open('config.json')).get('auto_map'))"

Some libraries built on top of transformers or huggingface_hub perform their own separate download or version-check calls that are not covered by TRANSFORMERS_OFFLINE alone, since that variable only affects transformers' own logic, not every library in a larger pipeline that happens to also touch the Hub.

Fix: Trace exactly which library and call is making the network attempt (via a traceback or by tracing socket connections) and check whether that specific library has its own offline environment variable or requires an explicit local path argument.

python -X importtime script.py 2> import_trace.log

In a fully air-gapped network with no DNS server configured at all (rather than DNS working but the destination being unreachable), a network call can hang for the full OS-level DNS timeout before failing, making an offline-mode misconfiguration look like a hang or extreme slowness rather than an immediate, clear connection error.

Fix: Confirm DNS and outbound network are both fully disabled or fully enabled consistently in your test environment, since a half-configured network (DNS works, TCP connect fails) produces much longer, more confusing failure modes than either state alone.