huggingface-hub
The official Python client and CLI for the Hugging Face Hub. It handles the plumbing between your machine and huggingface.co: downloading model and dataset files into a shared local cache, uploading and versioning repos, writing model cards, searching the Hub, and calling hosted models through InferenceClient. It also ships the hf CLI, so hf download, hf upload, and hf jobs run cover the same ground from a terminal. If you have ever used transformers, this library was already underneath it fetching the weights.
If you touch the Hugging Face Hub from Python or CI, this is the library, and there is no real substitute. Treat major upgrades with care and keep an eye on the cache directory it fills.
Use it if
- You need model or dataset files from the Hub without pulling in all of transformers; hf_hub_download and snapshot_download are the direct route
- You publish models, datasets, or Spaces and want programmatic repo creation, uploads, and model cards instead of clicking around the website
- You want one shared local cache for weights across projects, with revision pinning and chunk dedup handled for you
- You call models through Hugging Face Inference Providers; InferenceClient gives you OpenAI-shaped chat completion against hosted models without managing GPUs
- You already depend on transformers or datasets; both install and drive huggingface-hub for you, so importing it directly only matters when you need Hub operations yourself
- Your artifacts live in S3, GCS, or an internal registry; this library is Hub-only glue and none of it applies off huggingface.co
- You dislike API churn: years of deprecation cycles ended in a breaking 1.0 that dropped long-deprecated names (the git-based Repository helper, InferenceApi, the huggingface-cli entry point in favor of hf), so older tutorials and pinned code routinely break on upgrade
- Disk space is tight: snapshot_download grabs every file in a repo by default, and the cache under ~/.cache/huggingface quietly grows to tens of GB across projects
Setup reality
pip install huggingface-hub is quick and the base package stays deliberately small, with extras like [mcp] for more. The friction is everything around it: gated models (Llama, Gemma) require accepting a license on the website plus hf auth login or an HF_TOKEN env var, CI needs a token with the right fine-grained scopes, and the cache under HF_HOME (default ~/.cache/huggingface) silently grows until you learn scan_cache_dir and the hf CLI cache commands. Code written before 1.0 may reference removed APIs, so check the migration notes when upgrading old projects.
Patterns
Download one file from a repodownload-single-file
from huggingface_hub import hf_hub_download
path = hf_hub_download(repo_id="Qwen/Qwen3-0.6B", filename="config.json")
print(path)Returns a path inside the shared cache, not a copy in your project; pass local_dir=... if you actually need the file next to your code.
Snapshot a whole repo, filtereddownload-full-repo
from huggingface_hub import snapshot_download
local = snapshot_download(
"sentence-transformers/all-MiniLM-L6-v2",
allow_patterns=["*.safetensors", "*.json", "*.txt"],
)Without allow_patterns you download every file in the repo, including duplicate weight formats; filtering can cut multi-GB pulls dramatically.
Log in for private and gated reposauthenticate
# one-time, interactive:
# hf auth login
# in code or CI:
from huggingface_hub import login
login(token="hf_...") # or just set the HF_TOKEN env varGated models also require accepting the license on the model page while logged in on the website; a valid token alone still gets you a 403.
Create a repo and upload a filecreate-repo-upload
from huggingface_hub import create_repo, upload_file
create_repo("username/my-model", exist_ok=True)
upload_file(
path_or_fileobj="model.safetensors",
path_in_repo="model.safetensors",
repo_id="username/my-model",
)Each upload_file call is one commit; for many files use upload_folder or you will spam the repo history.
Upload a folder as one commitupload-folder
from huggingface_hub import upload_folder
upload_folder(
folder_path="./checkpoints/final",
repo_id="username/my-model",
commit_message="Add final checkpoint",
)Large files go through Xet chunk dedup on the Hub side, so re-uploading a slightly changed checkpoint transfers far less than its full size.
Chat completion via Inference Providersinference-chat
from huggingface_hub import InferenceClient
client = InferenceClient()
resp = client.chat.completions.create(
model="meta-llama/Llama-3.1-8B-Instruct",
messages=[{"role": "user", "content": "Hi"}],
)
print(resp.choices[0].message.content)Follows the OpenAI response shape, but which models are actually deployed varies by provider; hf models ls --warm shows what is live before you code against it.
Search the Hub programmaticallysearch-models
from huggingface_hub import list_models
for m in list_models(task="text-classification", sort="downloads", limit=5):
print(m.id, m.downloads)Returns a lazy iterator of ModelInfo objects; without limit it will happily page through the entire Hub.
See what the cache is costing youmanage-cache
from huggingface_hub import scan_cache_dir
info = scan_cache_dir()
print(f"{info.size_on_disk / 1e9:.1f} GB in {len(info.repos)} repos")The cache location follows HF_HOME and keeps every revision you ever pulled; scan before your disk fills, and prune with the hf CLI cache commands rather than rm -rf.
Read and edit model cardsmodel-card
from huggingface_hub import ModelCard
card = ModelCard.load("google-bert/bert-base-uncased")
print(card.data.license)card.data is the structured YAML front matter and card.text is the markdown body; push edits back with card.push_to_hub.
Do it all from the terminalcli-download-upload
hf download Qwen/Qwen3-0.6B --local-dir ./qwen
hf upload username/my-cool-model ./model.safetensorsThe CLI is named hf now; older tutorials say huggingface-cli, which was this same tool before the rename, so translate commands accordingly.
Alternatives
| Package | Registry | Pick it when |
|---|---|---|
| transformers | PyPI | You want to load and run the models, not just move files; AutoModel handles the download through this library anyway |
| datasets | PyPI | You are after Hub datasets specifically; load_dataset streams and caches them without manual file handling |
| kagglehub | PyPI | Your models and datasets live on Kaggle instead of the Hugging Face Hub |