Frequently Asked Questions & Troubleshooting (FAQ)

The official command line tool huggingface-cli (powered by huggingface_hub) is the most robust way to fetch large AI models.

• Multi-threading & Resume: When a massive 20GB download is interrupted at 95%, adding --resume-download picks up exactly where it dropped off, whereas web browsers frequently abort and force a full restart.
• Zero Git History Bloat: Running git clone pulls every commit history and tree index, consuming excessive disk space and memory; furthermore, Git LFS easily times out leaving corrupted pointer stubs.
• Wildcard Filtering: Flags like --include "*.safetensors" pull only required model weights, skipping unneeded .bin or .onnx artifacts.

Running export in your terminal only impacts the active shell session. To persist across reboots, add it to your profile configuration:

# For Bash users
echo 'export HF_ENDPOINT="https://hf-mirror.net"' >> ~/.bashrc
source ~/.bashrc

# For Zsh users (default on macOS)
echo 'export HF_ENDPOINT="https://hf-mirror.net"' >> ~/.zshrc
source ~/.zshrc

[System.Environment]::SetEnvironmentVariable('HF_ENDPOINT', 'https://hf-mirror.net', [System.EnvironmentVariableTarget]::User)

Gated repositories require explicit author approval before weights can be retrieved:

1. Log in to Hugging Face, visit the model card (e.g., meta-llama/Llama-3.3-70B-Instruct), and accept the community license agreement;
2. Navigate to Account Settings and generate a Read Token: https://huggingface.co/settings/tokens;
3. Authenticate in your terminal by executing huggingface-cli login, or pass --token hf_xxxx directly into your download command.

* Security Reminder: HF-Mirror uses end-to-end transparent TLS forwarding. Your token verifies directly against official Hugging Face servers and is never intercepted or retained on our systems.

This occurs when Git LFS is not installed or initialized on your host, causing Git to checkout only SHA256 text descriptors.

Resolution:

# 1. Install git-lfs (Ubuntu/Debian example)
sudo apt-get install git-lfs
git lfs install

# 2. Enter your cloned repository and trigger large file pulling
git lfs pull

Inject the endpoint environment variable before importing the transformers or diffusers libraries:

import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.net"

from transformers import AutoTokenizer, AutoModelForCausalLM

model_name = "Qwen/Qwen2.5-7B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name)

Inject the environment variable in your Dockerfile or when starting the container:

# Inside Dockerfile
ENV HF_ENDPOINT=https://hf-mirror.net

# Or mount host cache to avoid redundant downloads when launching container
docker run -it -e HF_ENDPOINT="https://hf-mirror.net" \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  pytorch/pytorch:latest

HF-Mirror's core purpose is a high-throughput file-level distribution acceleration proxy. The web UI on Hugging Face includes discussions, active Spaces demos, interactive code sandboxes, and sensitive session cookies.

To protect developer privacy and eliminate intermediate MITM vulnerabilities, this site strictly proxies binary file download APIs and does not render web UI cards. When interactive browser requests are detected, we guide visitors to view the official Model Card.

Use the --include filter in huggingface-cli download:

export HF_ENDPOINT="https://hf-mirror.net"
huggingface-cli download bartowski/DeepSeek-R1-Distill-Qwen-7B-GGUF --include "*Q4_K_M.gguf" --local-dir ./