Hugging Face mirror quickstart | Hugging Bay

On this page

Hugging Face mirror

Set one environment variable and your usual tools download hosted models from Hugging Bay. Every file has a recorded SHA-256. For the model files we tested, it matched the value Hugging Face publishes.

1. Set one variable

Mac and Linux:

export HF_ENDPOINT=https://hf.huggingbay.xyz

Windows PowerShell:

$env:HF_ENDPOINT = "https://hf.huggingbay.xyz"

This lasts for the current terminal. To keep it, add the line to your shell profile.

2. Use your tool as usual

hf CLI

From huggingface_hub. One file:

hf download Qwen/Qwen2.5-0.5B-Instruct-GGUF qwen2.5-0.5b-instruct-q4_k_m.gguf

Whole repo

Keep parallel workers at 4. The default of 8 can hit our busy limit.

hf download sentence-transformers/all-MiniLM-L6-v2 --max-workers 4

huggingface_hub in Python

Set the variable before you import huggingface_hub.

import os
os.environ["HF_ENDPOINT"] = "https://hf.huggingbay.xyz"
from huggingface_hub import hf_hub_download
hf_hub_download("Qwen/Qwen2.5-0.5B-Instruct", "config.json")

Transformers

Set the variable before you import transformers.

import os
os.environ["HF_ENDPOINT"] = "https://hf.huggingbay.xyz"
from transformers import AutoModelForCausalLM, AutoTokenizer
tok = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")
model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct")

llama.cpp

Tested with llama-completion from llama.cpp b12121. llama-cli and llama-server take the same -hf flag.

llama-completion -hf Qwen/Qwen2.5-0.5B-Instruct-GGUF:Q4_K_M -p "The capital of France is" -n 8

Proof from a live test

Same bytes as Hugging Face. For qwen2.5-0.5b-instruct-q4_k_m.gguf (491,400,032 bytes) we serve SHA-256

74a4da8c9fdbcd15bd1f6d01d621410d31c6fc00986f5eb687824e7b93d7a9db

and Hugging Face publishes the same value for the same file. Check it yourself:

curl -sI https://hf.huggingbay.xyz/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf | grep -i x-linked-etag
curl -sI https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf | grep -i x-linked-etag

Or hash the downloaded file (Mac and Linux):

shasum -a 256 "$(hf download Qwen/Qwen2.5-0.5B-Instruct-GGUF qwen2.5-0.5b-instruct-q4_k_m.gguf)"

Live test results
Tool	Model	Result	Time
hf download	Qwen2.5 0.5B Instruct GGUF, Q4_K_M (491,400,032 bytes)	SHA-256 matches Hugging Face	12.0 s
hf download	SmolLM2 135M Instruct GGUF, Q4_K_M (105,454,432 bytes)	SHA-256 matches Hugging Face	5.5 s
hf_hub_download	Qwen2.5 0.5B Instruct, config.json	Downloaded	5.2 s
hf download, 4 workers	all-MiniLM-L6-v2, whole repo	3 of 4 runs passed; 1 hit a busy error right after a burst	11.7 to 15.1 s
Transformers	Qwen2.5 0.5B Instruct (988 MB)	Loaded and answered "Paris"	55.3 s
Transformers	all-MiniLM-L6-v2	Loaded, produced embeddings	36.8 s
llama.cpp -hf	SmolLM2 135M Instruct, Q4_K_M	Downloaded and answered "Paris"	8.7 s
llama.cpp -hf	gemma-3 270M it, Q4_K_M	Downloaded and answered	12.5 s
llama.cpp -hf	Qwen2.5 0.5B Instruct, Q4_K_M	Downloaded and answered "Paris"	16.5 s

Run on 5 Nov 2026 from one Linux computer (CPU only) on a home connection. Times are wall clock for one run, including program start. Not a benchmark; yours will differ.
With the default 8 parallel workers, 3 of 4 whole-repo runs failed with a busy error (429 or 503) after the client's retries. Use 4 workers.
LM Studio: not tested yet.
Ollama: our last test of an Ollama pull failed. A fix ships with this page, and we will add Ollama here after it passes a live test.

What we host

Served here

A subset of public repos, not the whole Hub. Browse them on hosted models, or pick a file and get its exact command on the download guide.
A hosted repo can carry only some files. If llama.cpp says no file matches your quant, it lists the ones we have.
Every file has a recorded SHA-256 you can compare after you download it.

Not served here

Repos we have not mirrored. They fail fast with a clear not found error, such as "Repository not found".
Gated repos (for example meta-llama) and private repos. We never bypass a gate.
Missing a model? Ask for it.

Go back to Hugging Face

No tool switches back on its own. Turn the variable off, then run the command again in a new process:

unset HF_ENDPOINT

Remove-Item Env:HF_ENDPOINT -ErrorAction SilentlyContinue

In Python, remove the os.environ["HF_ENDPOINT"] line, and turn off the shell variable too if you set it in step 1.

Common errors
You see	It means
Repository not found (RepoNotFound, 404)	We do not host that repo. Go back to Hugging Face for it (below), or ask for it.
File not found (EntryNotFound, 404)	We host the repo but not that file.
429 or 503 with Retry-After	We are busy. Wait the Retry-After seconds and use fewer workers.

Public metadata can lag privacy changes by about 5 minutes; every download is checked again. A hash checks bytes; it does not prove a model will load or run on your computer. Licenses are shown as labels on each model page. Not affiliated with Hugging Face.

For agents: agent client mirrors, llms.txt, SKILL.md.