{"id":29,"library":"huggingface-hub","title":"Hugging Face Hub","description":"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.","status":"active","version":"1.5.0","language":"python","source_language":"en","source_url":"https://github.com/huggingface/huggingface_hub","tags":["huggingface","huggingface-hub","model-download","model-hub","hf-cli","cache","upload","pretrained-models","gated-models"],"install":[{"cmd":"pip install huggingface-hub","lang":"bash","label":"Core install"},{"cmd":"pip install huggingface-hub[hf-xet]","lang":"bash","label":"With xet storage backend (chunk deduplication for large files)"},{"cmd":"pip install huggingface-hub[torch]","lang":"bash","label":"With PyTorch integration utilities"},{"cmd":"uvx hf version","lang":"bash","label":"CLI-only usage via uv (no install needed)"}],"dependencies":[{"reason":"Required. Used for safe concurrent cache access.","package":"filelock","optional":false},{"reason":"v5 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.","package":"requests (v<1.x) / httpx (v1.x+)","optional":false},{"reason":"Required for download progress bars.","package":"tqdm","optional":false}],"imports":[{"note":"Package name uses hyphens, import uses underscores: huggingface_hub.","wrong":"import huggingface-hub","symbol":"hf_hub_download","correct":"from huggingface_hub import hf_hub_download"},{"note":"Downloads entire repo. hf_hub_download is for single files. Use snapshot_download for full model checkpoints.","symbol":"snapshot_download","correct":"from huggingface_hub import snapshot_download"},{"note":"Programmatic login. Alternatively set HF_TOKEN env var. CLI: hf auth login","symbol":"login","correct":"from huggingface_hub import login"}],"quickstart":{"code":"from huggingface_hub import hf_hub_download, snapshot_download, login\nimport os\n\n# Authenticate (or set HF_TOKEN env var)\n# login(token=os.environ[\"HF_TOKEN\"])\n\n# Download a single file\nconfig_path = hf_hub_download(\n    repo_id=\"bert-base-uncased\",\n    filename=\"config.json\"\n)\nprint(config_path)  # local cached path\n\n# Download entire model repo\nmodel_dir = snapshot_download(repo_id=\"Qwen/Qwen2.5-0.5B-Instruct\")\nprint(model_dir)  # local directory with all model files\n\n# Upload a file\nfrom huggingface_hub import upload_file\nupload_file(\n    path_or_fileobj=\"./my_model.bin\",\n    path_in_repo=\"model.bin\",\n    repo_id=\"your-username/your-model\",\n    token=os.environ[\"HF_TOKEN\"]\n)\n\n# Search models\nfrom huggingface_hub import HfApi\napi = HfApi()\nmodels = list(api.list_models(filter=\"text-classification\", limit=5))\nfor m in models:\n    print(m.id)","lang":"python","description":"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."},"warnings":[{"fix":"Update scripts to use hf auth login. huggingface-cli remains as a compatibility alias.","message":"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.","severity":"breaking","affected_versions":">=1.0"},{"fix":"Update HTTP mocking to use httpx. Do not assume requests is the underlying transport.","message":"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.","severity":"breaking","affected_versions":">=1.0"},{"fix":"Set HF_TOKEN env var with a token that has accepted the model's license at huggingface.co/settings/tokens.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"To force re-download, delete the cached repo from HF_HOME or pass force_download=True.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always: pip install huggingface-hub (hyphen). Always: import huggingface_hub (underscore).","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T04:54:40.170Z","next_check":"2026-05-28T00:00:00.000Z","problems":[{"fix":"Run `pip install huggingface-hub` or `conda install -c conda-forge huggingface-hub` to install the library.","cause":"The `huggingface-hub` package is not installed in the current Python environment or there is an environment mismatch.","error":"ModuleNotFoundError: No module named 'huggingface_hub'"},{"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.","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).","error":"ValueError: Invalid token passed!"},{"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.","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.","error":"command not found: hf"},{"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.","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.","error":"RepositoryNotFoundError: 401 Client Error"},{"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`).","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.","error":"ImportError: cannot import name 'HfApi' from 'huggingface_hub'"}],"ecosystem":"pypi","meta_description":null,"install_score":40,"install_tag":"draft","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"draft","tag_description":"notable install failures or slow imports","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":14.9,"disk_size":"57.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.67,"mem_mb":14.9,"disk_size":"57.2M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.52,"mem_mb":14.9,"disk_size":"58M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":14.9,"disk_size":"58M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"torch","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.65,"mem_mb":14.9,"disk_size":"4.7G"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.03,"mem_mb":17.4,"disk_size":"62.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.03,"mem_mb":17.4,"disk_size":"62.4M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.85,"mem_mb":17.4,"disk_size":"63M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.9,"mem_mb":17.4,"disk_size":"63M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"torch","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.05,"mem_mb":17.4,"disk_size":"4.7G"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.04,"mem_mb":17.5,"disk_size":"53.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.09,"mem_mb":17.5,"disk_size":"53.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.1,"mem_mb":17.5,"disk_size":"54M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.04,"mem_mb":17.5,"disk_size":"54M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"torch","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.11,"mem_mb":17.6,"disk_size":"4.7G"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1,"mem_mb":18.4,"disk_size":"53.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.02,"mem_mb":18.4,"disk_size":"53.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.01,"mem_mb":18.4,"disk_size":"54M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.99,"mem_mb":18.4,"disk_size":"54M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"torch","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.14,"mem_mb":18.4,"disk_size":"4.7G"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.57,"mem_mb":14.3,"disk_size":"55.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.58,"mem_mb":14.3,"disk_size":"55.9M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"torch","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.54,"mem_mb":14.3,"disk_size":"57M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"hf-xet","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.54,"mem_mb":14.3,"disk_size":"57M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"torch","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":14.3,"disk_size":"6.5G"}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":-1},{"runtime":"python:3.10-slim","exit_code":-1},{"runtime":"python:3.11-alpine","exit_code":-1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":-1},{"runtime":"python:3.12-slim","exit_code":-1},{"runtime":"python:3.13-alpine","exit_code":-1},{"runtime":"python:3.13-slim","exit_code":-1},{"runtime":"python:3.9-alpine","exit_code":-1},{"runtime":"python:3.9-slim","exit_code":-1}]}}