| name | downloading-hf-models |
| description | Get the correct command syntax for downloading models from HuggingFace. Use when downloading models, running "hf download", or pulling models from HuggingFace repos. |
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
