HuggingFace Model Download

Command Pattern

Always use uv run with the HuggingFace Hub package as an inline dependency:

uv run --with huggingface_hub hf download <repo> <file> --local-dir <path>

Common Mistakes to Avoid

• Wrong: pip install huggingface_hub && huggingface-cli download ...
• Wrong: uv run hf download ... (missing --with)
• Wrong: uv run --with "huggingface_hub[cli]" ... (the [cli] extra doesn't exist, the CLI is included in the base package)

Syntax Reference

Download a specific file

uv run --with huggingface_hub hf download <org>/<repo> <filename> --local-dir <destination>

Download multiple files

uv run --with huggingface_hub hf download <org>/<repo> <file1> <file2> --local-dir <destination>

Download with glob pattern

uv run --with huggingface_hub hf download <org>/<repo> --include "*.gguf" --local-dir <destination>

Warning: Large GGUF models are often split into parts (e.g., model.gguf.part-000, .part-001, etc.). Use --include "*.gguf*" (note the trailing *) to match both single GGUFs and split parts. Use --dry-run first to check what files will be downloaded.

Download entire repo

uv run --with huggingface_hub hf download <org>/<repo> --local-dir <destination>

Notes

• HF_TOKEN environment variable is used automatically for gated models
• --local-dir places files directly in the target directory (no nested .cache structure)
• Downloads are resumable — re-running the same command skips already-downloaded files
• For GGUF models, download only the quant you need rather than the whole repo