Hub Essentials

This content was generated with the assistance of AI and should be verified against the official documentation of each tool and framework before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

This page was written against huggingface_hub 2.0.0, transformers 5.17.0 and the hf command-line client that ships with huggingface_hub, as checked on 2026-09-30. The old huggingface-cli command was removed in huggingface_hub 1.0; use hf (introduced in 0.34) instead. Older tutorials and books that still show huggingface-cli login or huggingface-cli download describe the same operations under the previous name, and this page shows the current hf form. transformers 5.17.0 declares a dependency on huggingface_hub below 2.0, so an environment that installs both resolves to the 1.x line of huggingface_hub; the hf commands and Python functions on this page exist with the same names and options there, but check the current release notes of both packages before pinning them together.

The Hugging Face Hub is a Git-based hosting service for machine-learning artefacts. Everything you need to run a model locally — weights, tokenizer, configuration, licence and documentation — lives in a repository you can download with one command. The rest of this sub-section builds on the four operations covered here: find a repository, read its card, authenticate if it is gated, and download and cache the files.

Repository types

The Hub has three kinds of repositories, selected by a repo type (model is the default everywhere).

Type What it holds Typical use in this sub-section

Model

Weights, tokenizer and config files, plus a model card (README.md).

The thing you download and run on-device.

Dataset

Data files (often Parquet) plus a dataset card.

Fine-tuning and evaluation data.

Space

A small web app (Gradio, Streamlit, Docker or static) that runs on Hugging Face infrastructure.

Trying a model in the browser before downloading it; hosting Spaces in production is out of scope here.

Each repository is a Git repository: it has branches, tags, commits and pull requests (refs/pr/<n>), so a download can be pinned to an exact revision. Large binary files are not stored in plain Git but through the Xet storage backend (see Xet storage). A repository ID has the form owner/name, for example openai/whisper-small.en.

The Hub’s own documentation for the three types is at Hugging Face — The Model Hub, Hugging Face — Datasets and Hugging Face — Spaces.

Searching and filtering

On https://huggingface.co/models the left-hand filters and the search box narrow the catalogue by:

  • Task — the pipeline_tag metadata value, such as automatic-speech-recognition, text-to-speech, image-classification or text-generation.

  • Library — the library_name value (transformers, ctranslate2, mlx, transformers.js, …​), which tells you which runtime can load the repository.

  • Apps — the local applications and runtimes that can run the model (for example llama.cpp), see Hugging Face — Local Apps.

  • Parameters (size), licence, language and inference provider filters.

The sort order can be changed to Trending, Most downloads, Most likes or Recently created/updated. Trending ranks by recent activity, so it surfaces new releases; downloads favours long-established models. Neither is a quality ranking, which is why the next page, Choosing Models & Licences, teaches how to read a card and check the licence.

The same search is available from the terminal with hf models ls:

Searching the Hub from the command line
# Trending models (the default ordering)
hf models ls --limit 10

# Small speech-recognition models that are not gated
hf models ls --pipeline-tag automatic-speech-recognition --no-gated --sort downloads --limit 10

# Everything from one author that llama.cpp can run, as JSON for scripting
hf models ls --author ggml-org --apps llama.cpp --limit 5 --json | jq -r '.[].id'

# Models by parameter count
hf models ls --search gemma --num-parameters min:1B,max:4B --limit 10

The flags (--search, --author, --pipeline-tag, --num-parameters, --no-gated, --apps, --sort, --limit, --json) are documented in the Hugging Face — hf CLI guide. --json is an alias of --format json, and -q prints only the repository IDs, one per line.

The same query from Python uses HfApi:

Listing models with HfApi
from huggingface_hub import HfApi

api = HfApi()  # reads HF_TOKEN from the environment when it is set
for model in api.list_models(
    filter="automatic-speech-recognition",
    sort="downloads",
    limit=5,
):
    print(model.id)

See Hugging Face — Search the Hub for the full set of list_models arguments.

Model cards

A model card is the README.md at the root of a model repository. It has two parts:

  • A YAML header (metadata) that the Hub uses for filtering and display: license, library_name, pipeline_tag, language, datasets, base_model, tags and structured evaluation results.

  • Markdown text with the description, intended uses, limitations and biases, training details and evaluation.

base_model (with the relation finetune, adapter, merge or quantized) is how you trace a GGUF or MLX re-upload back to the original model and its licence. hf models card prints a card (or only its metadata) from the terminal:

Reading a card without opening a browser
hf models card openai/whisper-small.en --metadata --format json
hf models card openai/whisper-small.en --text | head -40

Reading a card critically (intended use, evaluation, limitations) is covered in Choosing Models & Licences. Reference: Hugging Face — Model Cards.

Tokens and gated models

Most public repositories download anonymously. You need an access token for private repositories, for gated repositories and for anything that writes to the Hub. Create one under the account’s Settings → Access Tokens; prefer a fine-grained token limited to the repositories and permissions you need, and a read-only token for downloading. The details are in Hugging Face — User access tokens.

Never commit a token, paste it into a notebook that is shared, or bake it into an application you ship. Provide it through the HF_TOKEN environment variable (or the secret store of your CI system), and let the tools read it.

A gated model asks each user to agree to share their contact information (and sometimes to accept licence terms) before the files can be downloaded. Access is granted to individual users, never to an organisation as a whole. There are two approval modes, chosen by the model author:

  • Automatic approval — as soon as you click Agree and send request to access repo in the browser you can download.

  • Manual approval — the authors review requests, which can take time, and may reject them. The authors can revoke access at any time.

Requesting access can only be done in a browser while logged in; downloading the files afterwards needs the token. In the Hub API the gating mode shows up as the repository’s gated field (false, "auto" or "manual").

Downloading a gated repository after access was granted
export HF_TOKEN=...            # read token of the account that was granted access (never commit it)
hf auth whoami                 # confirms which account the token belongs to
hf download meta-llama/Llama-3.2-1B-Instruct --include "*.safetensors"
Logging in explicitly
hf auth login                      # interactive
hf auth login --token "$HF_TOKEN"  # non-interactive, e.g. in CI
hf auth logout

A gated repository is a distribution mechanism, not a licence: the licence terms are on the card and are a separate question (see the licence checklist in Choosing Models & Licences). Reference: Hugging Face — Gated models.

The hf CLI

hf is installed with pip install -U huggingface_hub (there are also a standalone installer, Homebrew and uvx hf options). The commands used most often:

Command Purpose

hf auth login, hf auth whoami, hf auth logout

Store, check and remove the access token.

hf download <repo> [files…​]

Download a whole repository or named files into the cache (or --local-dir).

hf models ls, hf models info, hf models card

Search models, show metadata, print the model card.

hf cache ls, hf cache rm, hf cache prune, hf cache verify

Inspect, delete, clean and checksum the local cache.

hf download accepts --include and --exclude glob patterns, --repo-type, --revision, --local-dir, --cache-dir and --dry-run. Filtering matters because most repositories hold the same weights in several formats:

Downloading only what you need
# Preview first: which files, how many bytes
hf download openai/whisper-small.en --include "*.safetensors" --dry-run

# One quantised GGUF file out of a repository that holds several
hf download ggml-org/gemma-3-1b-it-GGUF gemma-3-1b-it-Q4_K_M.gguf

# Pin a revision and place the files in a project folder instead of the cache
hf download openai/whisper-small.en --include "*.safetensors" \
  --revision main --local-dir ./models/whisper-small.en

# A dataset instead of a model
hf download --repo-type dataset google/fleurs --include "*.md" --dry-run

hf download prints the local path of what it fetched, which is convenient in scripts. Reference: Hugging Face — hf CLI guide.

The huggingface_hub 2.0 Python API

Everything the CLI does is available from Python. The two download functions are the ones application code uses:

  • hf_hub_download(repo_id, filename, …​) downloads one file, caches it in a version-aware way and returns the local path. Pass revision for a branch, tag, PR (refs/pr/3) or full commit hash, repo_type for datasets and Spaces, and local_dir to place the file in a folder.

  • snapshot_download(repo_id, …​) downloads a whole repository at a revision, in parallel, and returns the snapshot folder. allow_patterns and ignore_patterns filter the files like --include / --exclude.

Fetching files from Python
from huggingface_hub import hf_hub_download, snapshot_download

# One file, cached; returns its path
gguf_path = hf_hub_download(
    repo_id="ggml-org/gemma-3-1b-it-GGUF",
    filename="gemma-3-1b-it-Q4_K_M.gguf",
)

# A whole model, but only the safetensors weights and the JSON/text files
model_dir = snapshot_download(
    repo_id="openai/whisper-small.en",
    allow_patterns=["*.safetensors", "*.json", "*.txt"],
)
print(gguf_path, model_dir)

The returned paths point into the cache: treat them as read-only, because editing a cached file corrupts the cache. Pass local_dir when you want an editable copy or a folder you can ship with an application. Both functions accept a token argument, but the environment variable HF_TOKEN is the safer default. Both can also be called with dry_run=True to get the list of files that would be downloaded. Reference: Hugging Face — Download files from the Hub.

Libraries built on top of huggingface_hub (transformers, diffusers, sentence-transformers, llama-cpp-python’s `Llama.from_pretrained, faster-whisper) call these functions for you, so they share the same cache and token.

The cache and HF_HOME

Downloads go into a shared on-disk cache, so a model is fetched once and reused by every tool. The layout is models--<owner>--<name>/snapshots/<commit-hash>/…​, with the actual bytes in a blobs folder and symlinks in the snapshots, so two revisions that share a file store it once. The locations are controlled by environment variables:

Variable Meaning

HF_HOME

Root for local Hugging Face data, including the token. Defaults to ~/.cache/huggingface (or $XDG_CACHE_HOME/huggingface when XDG_CACHE_HOME is set).

HF_HUB_CACHE

Where model, dataset and Space repositories are cached. Defaults to $HF_HOME/hub. Takes priority over HF_HOME in transformers.

HF_XET_CACHE

Where Xet chunks are cached; defaults to $HF_HOME/xet.

HF_TOKEN

The access token; overrides a token stored by hf auth login.

HF_HUB_OFFLINE

When truthy (1), no HTTP call is made to the Hub.

Set them before huggingface_hub is imported, because they are read at import time. The older names HUGGINGFACE_HUB_CACHE and HUGGING_FACE_HUB_TOKEN are deprecated.

Moving the cache to a bigger disk
export HF_HOME=/mnt/models/huggingface
hf download openai/whisper-small.en

hf cache ls                       # what is cached and how big
hf cache ls --filter "size>1g"    # only the large repositories
hf cache prune --dry-run          # unreferenced revisions and incomplete downloads
hf cache rm model/openai/whisper-small.en   # remove one repository

hf cache prune removes unreferenced entries (detached revisions, incomplete downloads); hf cache rm deletes named repositories or revisions; hf cache verify compares cached files against the Hub’s checksums. On Windows the cache relies on symlinks, which need developer mode or an elevated process; without them files are duplicated. HF_HUB_DISABLE_SYMLINKS=1 turns symlinks off on purpose, for example for a network drive shared between operating systems. Reference: Hugging Face — Understand caching and Hugging Face — Environment variables.

Offline mode

An application that has to work without a network — the DocsAssistant goes offline scenario of this sub-section — downloads its models ahead of time and then stops talking to the Hub. There are two layers:

  1. Populate the cache (or a folder) while online, with hf download, snapshot_download or local_dir.

  2. Forbid network access at runtime with HF_HUB_OFFLINE=1, which makes huggingface_hub and transformers use only cached files and raise an error when something is missing. With the variable set, hf_hub_download also skips its "is there a newer version" request, which makes loading faster. Alternatively pass local_files_only=True to from_pretrained, or point from_pretrained at a local folder.

Loading from the cache with no network
import os
os.environ["HF_HUB_OFFLINE"] = "1"   # set before importing huggingface_hub / transformers

from transformers import pipeline

asr = pipeline(
    "automatic-speech-recognition",
    model="openai/whisper-small.en",   # resolved from the local cache only
)
print(asr("question.wav")["text"])

For a folder-based deployment, download with --local-dir and pass the folder path as the model name. Reference: Transformers — Offline mode.

Xet storage

Model files are large and binary, so the Hub does not keep them in ordinary Git or (any longer) in Git LFS. It stores them with Xet, a content-addressed storage backend that splits files into chunks and deduplicates them. The effect is that uploading a slightly changed checkpoint transfers only the changed chunks, and downloads can reuse chunks the client already has.

On the client side the work is done by the hf_xet package, which huggingface_hub installs as a dependency and uses automatically. You normally do nothing. The relevant settings are:

  • HF_XET_HIGH_PERFORMANCE=1 — use more network and CPU to maximise throughput on a fast machine. This replaces the deprecated HF_HUB_ENABLE_HF_TRANSFER / hf_transfer route, which no longer works.

  • HF_HUB_DISABLE_XET=1 — fall back to the non-Xet download path if hf_xet misbehaves.

  • HF_XET_CACHE — where chunks are cached.

References: Hugging Face — Xet: our storage backend and Hugging Face — Xet documentation.

References