huggingface-hub

name	huggingface-hub
description	HuggingFace Hub — download models/datasets, upload artifacts, search, and manage tokens via CLI and Python API.
version	1.0.0
author	hermes-CCC (ported from Hermes Agent by NousResearch)
license	MIT
metadata	{"hermes":{"tags":["MLOps","HuggingFace","Models","Datasets","Hub","Download","Upload"],"related_skills":["grpo-rl-training"]}}

HuggingFace Hub

Download models and datasets, upload artifacts, and manage your Hub presence via CLI and Python API.

Setup

pip install huggingface_hub datasets transformers
huggingface-cli login   # paste your token from hf.co/settings/tokens

Or set env var:

export HF_TOKEN=hf_...

---

Download Models

# Download entire model to cache (~/.cache/huggingface/)
huggingface-cli download meta-llama/Llama-3.1-8B-Instruct

# Download to specific directory
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/qwen

# Download specific file only
huggingface-cli download microsoft/phi-4 config.json

# Download GGUF quantized model
huggingface-cli download bartowski/Llama-3.1-8B-Instruct-GGUF \
  Llama-3.1-8B-Instruct-Q4_K_M.gguf --local-dir ./models/

Python API:

from huggingface_hub import snapshot_download, hf_hub_download

# Full model
snapshot_download("meta-llama/Llama-3.1-8B-Instruct", local_dir="./models/llama")

# Single file
hf_hub_download("meta-llama/Llama-3.1-8B-Instruct", "config.json", local_dir="./")

---

Download Datasets

# CLI
huggingface-cli download --repo-type dataset HuggingFaceH4/ultrachat_200k

# Python (preferred)
from datasets import load_dataset

dataset = load_dataset("HuggingFaceH4/ultrachat_200k")
dataset["train_sft"].to_json("./data/train.jsonl")

---

Upload Models

# Upload directory
huggingface-cli upload your-username/my-model ./local-model-dir

# Upload specific file
huggingface-cli upload your-username/my-model ./model.safetensors

# Create repo first if needed
huggingface-cli repo create my-new-model --type model

Python API:

from huggingface_hub import HfApi

api = HfApi()
api.upload_folder(
    folder_path="./fine-tuned-model",
    repo_id="your-username/my-fine-tuned-model",
    repo_type="model",
)

---

Search Models

# CLI search
huggingface-cli search models --filter task=text-generation --filter language=ko

# Python API
from huggingface_hub import list_models

models = list_models(
    task="text-generation",
    language="ko",
    sort="downloads",
    limit=10,
)
for m in models:
    print(m.id, m.downloads)

---

Cache Management

# Show cache info
huggingface-cli cache info

# List cached repos
huggingface-cli cache scan

# Delete specific cached model
huggingface-cli cache evict --model meta-llama/Llama-3.1-8B-Instruct

# Cache location
echo ~/.cache/huggingface/hub/

Custom cache dir:

export HF_HOME=/path/to/custom/cache

---

Model Cards

# Read model card
python -c "from huggingface_hub import ModelCard; print(ModelCard.load('Qwen/Qwen2.5-7B-Instruct'))"

---

Spaces

# Deploy a Gradio/Streamlit app to Spaces
huggingface-cli upload your-username/my-space ./app --repo-type space

# Check Space status
huggingface-cli space info your-username/my-space

---

Token Management

# Who am I?
huggingface-cli whoami

# List tokens
huggingface-cli token list

# Revoke
huggingface-cli token revoke TOKEN_NAME

---

Gated Models (Llama, Gemma, etc.)

1. Go to hf.co/model-card and accept terms
2. Use a token with read access: huggingface-cli login
3. Download normally — gate is checked server-side

# Check if you have access
from huggingface_hub import model_info
info = model_info("meta-llama/Llama-3.1-8B-Instruct")
print(info.gated)  # False if you have access