Registry / ai-ml / huggingface-hub

huggingface-hub

library1.28.0pypypi✓ verified 14d ago

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.

ai-ml llm-agents data http-networking devops

pip install huggingface-hub

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HUGGINGFACE-HUB

huggingface-hub

ai-mlpythonv1.28.0

Install

26.2s avg

Import

845ms

Disk

48MB

Pass rate

9/ 10

Env Coverage9 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.28.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 29.6s

py 3.11

✓ —

✓ 27.27s

py 3.12

✓ —

✓ 24.6s

py 3.13

✓ —

✓ 23.27s

py 3.9

✓ —

2/3 runs

48MB installed

● package 48MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

hf_hub_download

✓ from huggingface_hub import hf_hub_download

✗ import huggingface-hub

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.

✓ from huggingface_hub import login

Programmatic login. Alternatively set HF_TOKEN env var. CLI: hf auth login

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)

hf --version

Debug

Known issues

breakingThe 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.

affects: >=1.0

breakinghuggingface_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.

affects: >=1.0

gotchaGated 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.

affects: all

gotchasnapshot_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.

affects: all

gotchaPackage 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).

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'huggingface_hub'

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.

ValueError: Invalid token passed!

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.

command not found: hf

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.

RepositoryNotFoundError: 401 Client Error

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.

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

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`).

Upgrade

Version history

1.28.0latest on PyPI · released Aug 18, 2026

Audit

Dependencies

filelockrequiredRequired. Used for safe concurrent cache access.

requests (v<1.x) / httpx (v1.x+)requiredv5 of transformers dropped requests in favor of httpx. huggingface_hub 1.x follows this. Older code that assumes requests as the HTTP backend may see behavior changes.

tqdmrequiredRequired for download progress bars.

Agent activity

185 hits · last 30 days

node

172