Hugging Face Hub

1.5.0 verified Tue May 12 auth: no python install: draft quickstart: stale

Official Python client for the Hugging Face Hub. Handles model/dataset/Space downloading, uploading, caching, repo management, and Hub API interactions. Used as a dependency by transformers, datasets, sentence-transformers, and most HF ecosystem packages. The CLI was previously huggingface-cli; in v1.x it was rebranded as hf (also available as a standalone pip install hf package for CLI-only use). Import name: huggingface_hub (underscore). Package name: huggingface-hub (hyphen). These are different from the hf CLI package.

pip install huggingface-hub

Common errors

error ModuleNotFoundError: No module named 'huggingface_hub' ↓

cause The `huggingface-hub` package is not installed in the current Python environment or there is an environment mismatch.

fix

Run pip install huggingface-hub or conda install -c conda-forge huggingface-hub to install the library.

error ValueError: Invalid token passed! ↓

cause The provided Hugging Face access token is incorrect, expired, or was not correctly pasted (e.g., Ctrl+V might not work in some terminals, requiring a right-click or specific terminal paste command).

fix

Generate a new access token from your Hugging Face settings page (huggingface.co/settings/tokens). Then, try huggingface-cli login in your terminal and carefully paste the token, or use from huggingface_hub import login; login(token='hf_YOUR_TOKEN_HERE') in Python.

error command not found: hf ↓

cause The `hf` command-line interface is not installed, not in the system's PATH, or you might be trying to use the deprecated `huggingface-cli` command which has been replaced by `hf` in newer `huggingface_hub` versions.

fix

Ensure huggingface-hub is installed and up-to-date by running pip install --upgrade huggingface-hub. If huggingface-cli works but gives a deprecation warning, simply switch to using the hf command instead.

error RepositoryNotFoundError: 401 Client Error ↓

cause You are attempting to access a private or gated Hugging Face repository (model, dataset, or Space) without being properly authenticated or without having the necessary permissions for that specific repository.

fix

Log in to the Hugging Face Hub using huggingface-cli login in your terminal or programmatically with from huggingface_hub import login; login() in a notebook. Ensure your access token has sufficient permissions (read for download, write for upload) for the repository you are trying to access.

error ImportError: cannot import name 'HfApi' from 'huggingface_hub' ↓

cause This error typically indicates an outdated version of the `huggingface_hub` library or an incorrect import path for a function or class that has moved or been renamed in a newer release.

fix

Upgrade huggingface-hub to its latest version by running pip install --upgrade huggingface-hub. After upgrading, verify your import statements, ensuring core components like HfApi are imported directly from huggingface_hub (e.g., from huggingface_hub import HfApi).

Warnings

breaking The CLI command changed from huggingface-cli to hf in recent versions. huggingface-cli still works as an alias but hf is now the canonical name. CI scripts using huggingface-cli login should still work but new docs use hf auth login. ↓

fix Update scripts to use hf auth login. huggingface-cli remains as a compatibility alias.

breaking huggingface_hub switched from requests to httpx as the HTTP backend in v1.x (aligned with transformers v5). Code that patches or mocks requests for HF Hub calls will silently stop working. ↓

fix Update HTTP mocking to use httpx. Do not assume requests is the underlying transport.

gotcha Gated models (meta-llama/*, google/gemma-*, etc.) require: (1) a HF account, (2) accepted license on the model page, (3) a valid HF_TOKEN. from_pretrained() raises a 401/403 with a confusing error if any of these are missing. ↓

fix Set HF_TOKEN env var with a token that has accepted the model's license at huggingface.co/settings/tokens.

gotcha snapshot_download() and hf_hub_download() cache by default. Re-running always returns the cached version unless local_files_only=False and the remote has changed. In long-running services, stale model versions can persist silently. ↓

fix To force re-download, delete the cached repo from HF_HOME or pass force_download=True.

gotcha Package name is huggingface-hub (hyphen) but import name is huggingface_hub (underscore). pip install huggingface_hub (underscore) will NOT find the package on older pip versions and may install nothing or the wrong thing. ↓

fix Always: pip install huggingface-hub (hyphen). Always: import huggingface_hub (underscore).

Install

pip install huggingface-hub[hf-xet]

pip install huggingface-hub[torch]

uvx hf version

Install compatibility draft last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) huggingface-hub - - 0.65s 57.1M

3.10 alpine (musl) hf-xet - - 0.67s 57.2M

3.10 alpine (musl) torch - - - -

3.10 slim (glibc) huggingface-hub - - 0.52s 58M

3.10 slim (glibc) hf-xet - - 0.53s 58M

3.10 slim (glibc) torch - - 0.65s 4.7G

3.11 alpine (musl) huggingface-hub - - 1.03s 62.4M

3.11 alpine (musl) hf-xet - - 1.03s 62.4M

3.11 alpine (musl) torch - - - -

3.11 slim (glibc) huggingface-hub - - 0.85s 63M

3.11 slim (glibc) hf-xet - - 0.90s 63M

3.11 slim (glibc) torch - - 1.05s 4.7G

3.12 alpine (musl) huggingface-hub - - 1.04s 53.5M

3.12 alpine (musl) hf-xet - - 1.09s 53.5M

3.12 alpine (musl) torch - - - -

3.12 slim (glibc) huggingface-hub - - 1.10s 54M

3.12 slim (glibc) hf-xet - - 1.04s 54M

3.12 slim (glibc) torch - - 1.11s 4.7G

3.13 alpine (musl) huggingface-hub - - 1.00s 53.2M

3.13 alpine (musl) hf-xet - - 1.02s 53.2M

3.13 alpine (musl) torch - - - -

3.13 slim (glibc) huggingface-hub - - 1.01s 54M

3.13 slim (glibc) hf-xet - - 0.99s 54M

3.13 slim (glibc) torch - - 1.14s 4.7G

3.9 alpine (musl) huggingface-hub - - 0.57s 55.9M

3.9 alpine (musl) hf-xet - - 0.58s 55.9M

3.9 alpine (musl) torch - - - -

3.9 slim (glibc) huggingface-hub - - 0.54s 57M

3.9 slim (glibc) hf-xet - - 0.54s 57M

3.9 slim (glibc) torch - - 0.63s 6.5G

Imports

hf_hub_download
wrong
```
import huggingface-hub
```
correct
```
from huggingface_hub import hf_hub_download
```
Package name uses hyphens, import uses underscores: huggingface_hub.
snapshot_download
```
from huggingface_hub import snapshot_download
```
Downloads entire repo. hf_hub_download is for single files. Use snapshot_download for full model checkpoints.
login
```
from huggingface_hub import login
```
Programmatic login. Alternatively set HF_TOKEN env var. CLI: hf auth login

Quickstart stale last tested: 2026-05-12

Files are cached locally in HF_HOME (default: ~/.cache/huggingface). hf_hub_download returns local path. Gated models (Llama, Gemma) require login() or HF_TOKEN with accepted license.

from huggingface_hub import hf_hub_download, snapshot_download, login
import os

# Authenticate (or set HF_TOKEN env var)
# login(token=os.environ["HF_TOKEN"])

# Download a single file
config_path = hf_hub_download(
    repo_id="bert-base-uncased",
    filename="config.json"
)
print(config_path)  # local cached path

# Download entire model repo
model_dir = snapshot_download(repo_id="Qwen/Qwen2.5-0.5B-Instruct")
print(model_dir)  # local directory with all model files

# Upload a file
from huggingface_hub import upload_file
upload_file(
    path_or_fileobj="./my_model.bin",
    path_in_repo="model.bin",
    repo_id="your-username/your-model",
    token=os.environ["HF_TOKEN"]
)

# Search models
from huggingface_hub import HfApi
api = HfApi()
models = list(api.list_models(filter="text-classification", limit=5))
for m in models:
    print(m.id)