huggingface

📋 Tips & Best Practices

1. Prefer --local-dir over default cache for reproducible paths

The default cache uses content-addressed symlinks. Use --local-dir ./models/name when you need a stable, self-contained directory for an application.

2. Pin revisions in production

Always pass --revision in production downloads. Branches like main are mutable and can silently update between runs.

3. Use --include/--exclude to skip unnecessary weights

Large models ship both .bin and .safetensors formats. Download only what your framework uses:

huggingface-cli download  --include "*.safetensors" --exclude "*.bin"

4. Pre-populate cache before going offline

huggingface-cli download         # fills cache
export HF_HUB_OFFLINE=1                 # subsequent loads use cache only

5. Use fine-grained tokens with minimal scope

Create per-project tokens at https://huggingface.co/settings/tokens — read-only tokens cannot accidentally delete or overwrite repos.

6. Commit model cards alongside weights

Every upload is a git commit. Include a README.md (model card) in the upload folder so the repo is immediately browseable on the Hub.

7. Use upload-large-folder for models over ~50 GB

upload-large-folder uses multi-part upload with automatic retry and deduplication — far more reliable than upload for very large checkpoints.

---