HuggingFace Hub

HuggingFace Hub overview

HuggingFace Hub is the central distribution platform for open-source AI models, datasets, and Spaces (demo apps). It hosts 500K+ models and 100K+ datasets, all versioned with Git and Git-LFS. Models can be loaded directly into transformers with a model ID string. The huggingface_hub Python library provides programmatic access: downloading, uploading, searching, and managing repositories. Access is free for public repos; private repos require a paid plan.

Downloading models and datasets

from huggingface_hub import snapshot_download, hf_hub_download
import os

# Set your token for gated models (Llama 3, Gemma etc)
os.environ["HF_TOKEN"] = "hf_..."  # or huggingface-cli login

# Download entire model repo to local cache
local_dir = snapshot_download(
    repo_id="meta-llama/Llama-3-8B-Instruct",
    ignore_patterns=["*.gguf", "original/*"],  # skip large alternate formats
    cache_dir="~/.cache/huggingface/hub",       # default cache location
)
print(f"Downloaded to: {local_dir}")

# Download a single file
config_path = hf_hub_download(
    repo_id="meta-llama/Llama-3-8B-Instruct",
    filename="config.json",
)

# Load with transformers (handles caching automatically)
from transformers import AutoModelForCausalLM, AutoTokenizer
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3-8B-Instruct")
# First call downloads; subsequent calls load from cache

Uploading your model

from huggingface_hub import HfApi, create_repo
import os

api = HfApi(token=os.environ["HF_TOKEN"])

# Create a new repository
repo_url = create_repo(
    repo_id="your-username/my-finetuned-llama3",
    private=True,         # private until ready to share
    exist_ok=True,
)

# Upload an entire directory
api.upload_folder(
    folder_path="./fine-tuned-llama3/merged",
    repo_id="your-username/my-finetuned-llama3",
    repo_type="model",
    commit_message="Upload fine-tuned Llama 3 8B",
    ignore_patterns=["*.tmp", "__pycache__/*"],
)

# Or use transformers' push_to_hub directly
from transformers import AutoModelForCausalLM, AutoTokenizer
model.push_to_hub("your-username/my-finetuned-llama3")
tokenizer.push_to_hub("your-username/my-finetuned-llama3")

Model cards and metadata

from huggingface_hub import ModelCard, ModelCardData

# Create a model card programmatically
card_data = ModelCardData(
    language=["en"],
    license="llama3",
    base_model="meta-llama/Llama-3-8B-Instruct",
    tags=["llama", "fine-tuned", "qlora"],
    datasets=["my-org/my-dataset"],
    metrics=[{"type": "accuracy", "value": 0.87, "dataset": {"name": "my-eval"}}],
)
card = ModelCard(
    content=(
        "---
" + card_data.to_yaml() + "
---
"
        "# My Fine-tuned Llama 3 8B
"
        "Fine-tuned on domain-specific data using QLoRA.
"
        "## Training details
"
        "- Base: meta-llama/Llama-3-8B-Instruct
"
        "- Method: QLoRA r=16
"
        "- Dataset: 10k instruction pairs
"
    ),
)
card.push_to_hub("your-username/my-finetuned-llama3")

Private and gated models

import os
from huggingface_hub import login

# Login (stores token in ~/.cache/huggingface/token)
login(token=os.environ["HF_TOKEN"])

# For gated models (Llama 3, Gemma): first accept the license on the model page
# then your token grants download access
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3-8B-Instruct",
    token=os.environ["HF_TOKEN"],  # explicit token if not logged in
)

# Make your own model gated (requires org plan):
from huggingface_hub import HfApi
api = HfApi()
api.update_repo_settings(
    repo_id="your-org/proprietary-model",
    gated=True,  # users must accept terms to download
)

Using Hub in CI/CD pipelines

import os
from huggingface_hub import HfApi

def push_to_hub_on_eval_pass(model_path: str, eval_score: float, threshold: float = 0.85):
    if eval_score < threshold:
        print(f"Eval {eval_score:.2f} below threshold {threshold} — skipping push")
        return

    api = HfApi(token=os.environ["HF_TOKEN"])
    api.upload_folder(
        folder_path=model_path,
        repo_id="my-org/production-model",
        commit_message=f"Auto-push: eval_score={eval_score:.3f}",
        create_pr=True,  # create a PR rather than pushing directly to main
    )
    print(f"Pushed to Hub with eval score {eval_score:.2f}")

# In your CI pipeline (GitHub Actions, etc):
# HF_TOKEN: ${{ secrets.HF_TOKEN }}
# python -c "from train import evaluate; score = evaluate(); push_to_hub_on_eval_pass('./model', score)"

Gotchas

• Cache location and size: The default cache at ~/.cache/huggingface/hub can grow to hundreds of GB if you download many models. Set HF_HOME or TRANSFORMERS_CACHE to a larger drive, and periodically run huggingface-cli delete-cache to reclaim space.
• Offline mode: Set TRANSFORMERS_OFFLINE=1 to prevent any network calls — all model loads will use the local cache. Essential for air-gapped deployments.
• Git-LFS limits: The free Hub tier has a 10GB storage quota for private repos. Large model repos (70B+) need a paid plan or should host weights in your own storage and use Hub only for metadata/tokenizer.
• Gated model access: Accept the license agreement on the model's web page before downloading. Token-only authentication fails without prior web acceptance.