Set the HF_HUB_OFFLINE environment variable. The Hugging Face Hub library documents that, when set, no HTTP calls are made to the Hub and only cached files are used, raising an error if a file is not cached. Pre-fetch a pinned revision, ship the cache with the service, and test with the network off.
Why production should not talk to the Hub
A service that downloads a model at startup depends on a public website being up, on the repository not changing, and on your network allowing the call. Each of those is a risk. The repository owner can push a new commit. The site can be unreachable during your incident. A change in the repo can change what your service loads.
Offline mode removes the dependency. The service runs from files you already vetted. That fits regulated environments and air-gapped ones, and it makes startup faster and more predictable.
What the setting does
The library's environment variable reference says that with HF_HUB_OFFLINE set, no HTTP calls will be made to the Hub. Download calls read from the cache, and if the cache lacks the file, an error is raised. The reference adds that calling methods on the API client in offline mode raises an offline mode exception.
So offline mode is a guard, not a downloader. It fails closed. You still need to fill the cache before it works.
Steps to set it up
- Choose and review the model. Do the intake review once, including license, file format and a first load in a sandbox.
- Pin the revision. Download using a specific commit hash, not a branch name. The download guide shows a revision parameter that accepts a tag, branch, pull request reference or commit hash. A hash cannot move.
- Fetch only what you need. Ask for the weights file in a safe format and the config files, not the whole repository.
- Build the cache in a controlled place. Use a build job or an internal machine. The cache default location is under the home directory in a huggingface folder, and it can be changed with the HF_HOME or HF_HUB_CACHE variables.
- Ship the cache. Mount it as a read-only volume or copy it into the deployment artifact. Record the hash of each file.
- Turn on offline mode in the service environment.
- Test with no network. Start the service in a container with networking disabled and confirm it loads and answers.
export HF_HOME=/srv/hf-cache
export HF_HUB_OFFLINE=1
python serve.py --model-id ORG/MODEL
Things that surprise people
| Surprise | What to do |
|---|---|
| Startup fails with a missing file error | The cache lacks a file the loader wants, such as a tokenizer. Fetch it during the build and retest |
| A different revision loads | Make sure the loader is pointed at your pinned revision and cache |
| Some other library still calls the internet | Offline mode covers the Hub library, so also block egress at the network layer |
| Updates never arrive | That is the point. Add a scheduled, reviewed process to move to a new revision |
The last row is a process question. Offline does not mean frozen forever. Plan how a new revision is reviewed, tested and promoted.
Pair it with egress control
An environment variable is a software setting. Add a network rule that blocks outbound traffic from the inference service to the internet. Then, even if some code path ignores the setting, it cannot fetch a different model.
Quick check
Does offline mode check that my files are safe?
No. It only stops network calls. The safety checks happen when you review and pin the model before you fill the cache.
Where does the cache live by default?
Under the home directory in a huggingface folder, according to the Hub library docs. Use the HF_HOME or HF_HUB_CACHE variables to move it.
Where Safeguard fits
Safeguard offers dependency scanning and policies and gates in CI, which help you keep the loader libraries around a pinned model current and reviewed. A free scan is available.
Sources
- huggingface_hub environment variables, read 19 October 2026.
- huggingface_hub download guide, read 19 October 2026.
- huggingface_hub cache guide, read 19 October 2026.
Last reviewed: 19 October 2026.
