Ask the Hub questions instead of browsing it

The website is one client of an API

Everything the Hub shows you is available as JSON, and the huggingface_hub package wraps it. This matters for three jobs the browser is bad at: answering questions about many repositories at once, checking things before you download them, and automating the boring parts of publishing.

pip install -U huggingface_hub

Listing models with the filters you would have clicked

from huggingface_hub import HfApi

api = HfApi()

models = api.list_models(
    task="automatic-speech-recognition",
    library="transformers",
    language="hi",
    sort="downloads",
    direction=-1,
    limit=20,
)

for m in models:
    print(f"{m.downloads:>9,}  {m.id}")

This is the URL from the search lesson, in code, and it returns objects you can filter further in Python, which is where it stops being a browser replacement and starts being useful. “Speech models for Hindi, updated in the last year, under Apache 2.0” is three lines of list comprehension and is not a query the sidebar can express.

Checking size before you download

The most valuable call is the one that costs nothing:

info = api.model_info("openai/whisper-large-v3", files_metadata=True)

total = sum(f.size or 0 for f in info.siblings)
print(f"{len(info.siblings)} files, {total / 1e9:.1f} GB")
for f in sorted(info.siblings, key=lambda s: -(s.size or 0))[:5]:
    print(f"  {(f.size or 0)/1e9:6.2f} GB  {f.rfilename}")

Run that before any snapshot_download and you will stop being surprised by disk usage. It also shows the duplicate-format problem from the last lesson immediately: you will see the .bin and the .safetensors sitting next to each other, each several gigabytes.

model_info also carries info.tags, info.cardData (the parsed YAML front matter of the card, including licence and base_model), info.gated, and info.lastModified. Everything the card page shows in a badge is in there as a field.

Downloading precisely

from huggingface_hub import hf_hub_download, snapshot_download

# one file
cfg = hf_hub_download("openai/whisper-large-v3", "config.json")

# a subset, pinned, skipping duplicate formats
path = snapshot_download(
    "openai/whisper-large-v3",
    revision="06f233fe06e710322aca913c1bc4249a0d71fce1",
    allow_patterns=["*.safetensors", "*.json", "*.txt"],
    ignore_patterns=["*.bin", "onnx/*"],
)

allow_patterns and ignore_patterns are the difference between a 6 GB download and a 12 GB one on repositories that ship several formats. Set HF_HUB_ENABLE_HF_TRANSFER=1 in the environment after pip install hf_transfer if your connection is fast enough to be bottlenecked by Python rather than the network; on a slow link it makes no difference.

Writing: repositories, files, and the commit you can see

api.create_repo("your-name/your-model", repo_type="model", private=True)

api.upload_file(
    path_or_fileobj="README.md",
    path_in_repo="README.md",
    repo_id="your-name/your-model",
    commit_message="Add model card with licence and limitations",
)

api.upload_folder(
    folder_path="./out",
    repo_id="your-name/your-model",
    ignore_patterns=["*.ckpt", "runs/*", "*.log"],
)

Every write is a commit with a message, visible in History. Use the message: six months later it is the only record of why a checkpoint changed.

The command line does the same things

hf auth login
hf download openai/whisper-small --include "*.safetensors" "*.json"
hf upload your-name/your-model ./out --commit-message "first checkpoint"
hf repo create your-name/your-dataset --repo-type dataset
hf cache scan

The binary was called huggingface-cli until 2025 and both names still appear in tutorials. hf cache scan is the one to remember; it prints what your cache is holding and is the quickest way to find the 40 GB you cannot account for.

What the API will not give you

• Rate limits are real. Anonymous calls are limited more tightly than authenticated ones, and a loop over ten thousand model_info calls will start getting HTTP 429. Authenticate, batch, and cache results to disk.
• downloads is a thirty-day count, not a total, and the next lesson explains what it counts.
• The API cannot tell you whether a model is good. Every field is either a counter or something the uploader typed. There is no quality signal in the JSON, and treating downloads as one is the mistake this whole module exists to prevent.

Do this now

Write ten lines that list the twenty most-downloaded models for a task you care about, and print each one’s licence from cardData. You will find that several of the top results have no licence field at all, which, as the card lesson argued, is not the same as permissive.