Hugging Face

Sefism.

Chapter 01

The Hub

The shared home for models, datasets and demo apps, and the account and tooling you need to use it from code.

Hub repositories

Also called model repo, dataset repo, repo id

What
Every model, dataset and Space on the Hub is a Git-based repository with an id of the form owner/name, such as Qwen/Qwen3-8B. Large files are stored with Git LFS or Xet storage.
Why
Libraries download by repo id, so one string is enough to load weights, config and tokeniser.

Watch out

Relying on the latest commit in production; pin a revision (a tag or commit hash) so an upstream change cannot break you.

The hf CLI and login

Also called huggingface-cli, hf auth login, HF_TOKEN

What
The hf command line tool (the successor to huggingface-cli) logs in, downloads and uploads files. Authentication uses an access token, either stored by hf auth login or read from HF_TOKEN.
Why
Gated models, private repos, uploads and higher rate limits all need a token.
Shell
pip install -U huggingface_hub
hf auth login
hf auth whoami
hf download Qwen/Qwen3-0.6B --local-dir ./qwen
hf upload my-user/my-model ./out .

Watch out

Committing a token to a repository or notebook; use fine-grained, read-only tokens where you can.

Model cards

Also called README.md, metadata

What
The README of a model repo: what the model is for, how it was trained, its evaluation results, limitations and intended use, plus YAML metadata such as licence, tags and base model.
Why
It is where you check whether a model suits your task and whether you may use it at all.

Watch out

Picking a model by download count without reading its intended use and known limitations.

Licences and gated models

Also called license, gated access

What
Each repo declares a licence, such as Apache 2.0, MIT or a custom model licence with usage conditions. Gated repos require you to accept terms before downloading.
Why
The licence decides whether you can use the model commercially, fine-tune it and redistribute the result.

Watch out

Assuming "open weights" means a permissive licence; many model licences restrict use or require attribution.

Spaces

Also called Gradio, demo app

What
Spaces host small apps, usually built with Gradio or as a Docker container, directly from a Hub repo, on free CPU or paid GPU hardware.
Why
Sharing a working demo of a model without running your own server.
Python
import gradio as gr
from transformers import pipeline

clf = pipeline("sentiment-analysis", model="my-org/ticket-sentiment")

def predict(text):
    return clf(text)[0]["label"]

demo = gr.Interface(fn=predict, inputs="text", outputs="text")
demo.launch()

The local cache

Also called HF_HOME, hf cache

What
Downloads are stored once in a shared cache (by default under ~/.cache/huggingface) and reused by every library. HF_HOME moves it.
Why
Models are large; the cache avoids downloading them again and lets you work offline with HF_HUB_OFFLINE=1.

Watch out

Filling a small home or container disk with model weights; point HF_HOME at a larger volume.

huggingface_hub in Python

Also called hf_hub_download, snapshot_download, HfApi

What
The huggingface_hub library downloads single files or whole repos, creates repos, uploads folders and searches the Hub from Python.
Why
Scripts and pipelines can fetch artefacts or publish results without shelling out to the CLI.
Python
from huggingface_hub import hf_hub_download, snapshot_download

path = hf_hub_download("sentence-transformers/all-MiniLM-L6-v2",
                       "config.json")
folder = snapshot_download("Qwen/Qwen3-0.6B",
                           allow_patterns=["*.json", "*.safetensors"])

Go deeper

01 · The Hub1 / 9