home / skills / trevors / dot-claude / hf-model-download

hf-model-download skill

safe

This skill provides the exact uv run command to download HuggingFace models with huggingface_hub, ensuring correct syntax and local directory handling.

npx playbooks add skill trevors/dot-claude --skill hf-model-download

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.9 KB

---
name: HuggingFace Model Download
description:
  When downloading models from HuggingFace, use this skill to get the correct
  command syntax. Triggers on "download model", "hf download", "huggingface
  download", "get model from huggingface", "pull model".
---

# HuggingFace Model Download

## Command Pattern

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

```bash
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

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

### Download multiple files

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

### Download with glob pattern

```bash
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

```bash
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

Overview

This skill provides the correct command patterns to download models and files from the HuggingFace Hub using the HuggingFace Hub CLI as an inline dependency. It focuses on reliable, resumable downloads, handling large GGUF files, and avoiding common syntax mistakes. Use it to generate exact uv run commands for single files, multiple files, glob patterns, or entire repos.

How this skill works

The skill constructs uv run commands that include the huggingface_hub package via --with so the hf CLI is available inline. It produces variants for single-file downloads, multiple files, glob patterns (including split GGUF parts), and full-repo pulls. It also incorporates best practices like using --local-dir for clean output and recommending --dry-run to preview matches.

When to use it

You need a reproducible command to download a model file from HuggingFace Hub.
You want to download multiple files or a full repo into a specific local directory.
You must fetch large GGUF models that may be split into parts.
You want resumable downloads or to avoid nested .cache directories.
You need to use HF_TOKEN for gated model access.

Best practices

Always run commands with uv run --with huggingface_hub so the CLI is available inline.
Use --local-dir <path> to place files directly into the target directory without .cache nesting.
Run --dry-run first when using glob patterns to verify which files will be matched.
When downloading GGUF models, include a trailing * in the glob (e.g., "*.gguf*") to match split parts, and download only the quant you need.
Rerun the same command to resume — already-downloaded files are skipped automatically.

Example use cases

Download a single file: uv run --with huggingface_hub hf download org/repo filename --local-dir ./models
Download multiple files: uv run --with huggingface_hub hf download org/repo file1 file2 --local-dir ./models
Download GGUF parts with glob: uv run --with huggingface_hub hf download org/repo --include "*.gguf*" --local-dir ./models --dry-run
Pull entire repo: uv run --with huggingface_hub hf download org/repo --local-dir ./models
Access a gated model by ensuring HF_TOKEN is set in the environment before running the command.

FAQ

Can I pip install huggingface_hub and then run hf download?

Avoid that pattern; prefer uv run --with huggingface_hub so the CLI runs inline. Installing and invoking a separate CLI can lead to version and path issues.

How do I ensure I download split GGUF model parts?

Use --include "*.gguf*" (note the trailing asterisk) to match both single GGUF files and part files like model.gguf.part-000. Use --dry-run to preview matched files.