A thin wrapper that reroutes HuggingFace through a mirror

What it does

hf_download.py is a thin Python wrapper around huggingface-cli and hf_transfer. It automates downloads of models and datasets from the HuggingFace mirror hf-mirror.com, and it will quietly install the underlying official tools if they are missing. The script adds basic file filtering with --include and --exclude patterns, plus token support for gated models like the Llama family.

The interesting bit

The author openly admits this began as a personal convenience script, which explains its pragmatic—if slightly rough—design. For example, specifying a custom --save_dir still forces a temporary cache in ~/.cache/huggingface/hub before files are moved to their final destination. It is glue code, but it is honest glue code.

Key highlights

• Wraps official huggingface-cli and hf_transfer; auto-installs them if absent.
• Pulls from hf-mirror.com by default, with a flag to disable mirroring.
• Supports --include and --exclude glob patterns to cherry-pick files from large repos.
• Handles gated models via --token (e.g., Meta’s Llama weights).

Caveats

• Specifying a custom --save_dir still temporarily caches files in ~/.cache/huggingface/hub, so that drive needs spare disk space.
• The README contains a typo (--exlucde) and warns that hf_transfer versions below 0.1.4 suppress the progress bar.
• The author notes this is a simple wrapper built for personal habit; advanced users should modify it or use the official CLI directly.

Verdict

Grab this if you are behind a slow or unstable link to the main HuggingFace hub and want a one-shot script that handles mirroring, token auth, and selective file downloads. Skip it if you already have a working mirror setup or need fine-grained control over cache management.