huggingface_hub: The Official Client for the Hugging Face Hub
The official CLI and Python client for the Hugging Face Hub.
At a glance
- What is it?
- A Python library and an hf CLI that cover downloads, uploads, repository management, Inference Providers, Jobs and storage buckets against huggingface.co. The package is small by default and pulls in optional extras only when you ask for them, which is the design decision worth understanding before you adopt it.
- Who is it for?
- Adopt huggingface_hub if your code already lives on huggingface.co: the hf CLI covers login, download, upload, bucket sync and Jobs from one binary, and the Python library exposes the same surface for scripts and training loops. Do not adopt it if you only need to fetch a single public file over HTTPS, since an HTTP client and a URL do that without adding a dependency.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem huggingface_hub exists to remove
Anyone who has pulled a pretrained checkpoint by hand knows the shape of the work: construct a URL, guess the filename, handle redirects, cache the result somewhere sane, and repeat the whole exercise for the tokenizer, the config and the dataset. huggingface_hub exists to collapse that into one call. The README frames the library as the way to "Download files from the Hub", "Upload files to the Hub" and "Manage your repositories", and it ships in a single package with two front ends: an hf CLI for the terminal and a huggingface_hub library for Python. The intended audience is broad. It covers a researcher who wants one model on a laptop, a team publishing weights and model cards under a username, and automation that runs Jobs on Hugging Face infrastructure. The README also states that both interfaces are "designed to work well for humans and AI agents", which is a positioning claim rather than an architectural one, and the material does not quantify what that changes in practice.
Two front ends, one HTTP surface
The architecture visible in the README is a shared client underneath two presentation layers. The CLI is the entry point that gets installed by a standalone script on macOS, Linux and Windows, and the Python package is installed with pip or uv. Both reach the same Hub endpoints. The README lists the capability set once and then notes you can do all of it "from the terminal with the hf CLI", which implies the CLI is a wrapper rather than a separate implementation. That matters for adoption: a bug in download retry logic or in revision pinning is a single fix, not two. It also means you can prototype with hf commands and then move the same operation into Python without learning a second mental model. The split that is not shared is authentication state. hf auth login writes credentials for the CLI, and the README points at the Hub token documentation for how applications authenticate, noting that --token $HF_TOKEN is the non-interactive path. In Python you supply the token yourself. Nothing in the material describes a shared credential store between the two, so treat them as separately configured.
Installing the CLI and the library, and what the extras cost
The README gives the standalone installer first. On macOS and Linux it is a curl pipe into bash from https://hf.co/cli/install.sh, and on Windows it is a PowerShell one-liner that downloads and executes install.ps1. Piping a remote script into a shell is a supply-chain decision you are making on every run, so pin or vendor it if that matters to you. For Python, pip install huggingface_hub also installs the hf CLI, and the README suggests uv pip install huggingface_hub for speed. The design detail worth pausing on is the optional dependency split. The README states the package "comes with optional dependencies useful for some use cases" and keeps the default install minimal; the MCP module is the example given, installed as pip install "huggingface_hub[mcp]". This is a real trade-off. A minimal default keeps install time and dependency conflict surface down, but it means the import that works on your machine can fail on a colleague's until they add the extra. The installation guide is the place to check which extra corresponds to which module, and the README does not enumerate them.
The commands you actually type
The quick start is concrete enough to copy. After installation, hf auth login authenticates interactively, with --token $HF_TOKEN for environments where no prompt is possible. hf models ls --warm lists models served by Inference Providers. hf download Qwen/Qwen3-0.6B pulls a model by repo id. hf upload username/my-cool-model ./model.safetensors pushes a local file to your own repo. hf buckets sync ./checkpoints hf://buckets/username/my-bucket mirrors a local directory to a storage bucket. hf jobs run python:3.12 python -c "print('Hello from the cloud!')" executes a command on Hugging Face infrastructure using a container image. hf --help is the discovery path for everything else. For agent users the README adds hf skills add, which installs a command reference generated from your installed CLI for agents that read from .agents/skills, and hf skills add --claude for the variant that also covers Claude Code. Generating the reference from the installed binary rather than shipping a static document is the right call: the skill cannot drift from the CLI version it describes.
Where this is the wrong tool
The library assumes the Hub is in the picture. If your artefacts live in an S3 bucket, an internal registry or a git remote you already control, adding huggingface_hub buys you a dependency tree and a token to manage for no benefit. The same applies if you need exactly one public file at a known path: an HTTP client and a URL will do it, and the caching, authentication and repository abstractions are overhead. There is a second, sharper limitation. The README describes the package as minimal by default with optional dependencies layered on, which means the failure mode when something is missing is an ImportError at the point of use, not at install time. That is easy to miss in a long-running training script that imports a module deep in a code path. A third constraint is release cadence. The recent releases show v1.29.0, v1.30.0 and v1.31.0 landing on 2026-08-27, 2026-09-03 and 2026-09-10, roughly weekly. Patch-level fixes arrive quickly, but a fast-moving client against a hosted API means the version you pin determines which endpoints behave as your code expects. The release notes are the only reliable record of what changed between them.
What you would use instead, and how it differs
The realistic alternative for the download half of this library is git with Git LFS. It is a genuinely different approach: git tracks a working tree and history, and LFS swaps large files for pointers, so you clone a repository and get a checkout you can commit to. huggingface_hub is not a version control system. It fetches individual files by repo id and revision, and its repository management is a set of API calls against the Hub rather than a local branch model. If your workflow is "clone once, edit, push a branch, open a pull request", git is the natural fit and the README even points at community engagement through PRs. If your workflow is "pull this exact revision of this file into this cache directory and continue training", the file-oriented client skips the clone entirely. The two overlap on upload, and they diverge on everything around it: caching, partial downloads, and the non-download features such as Inference Providers, Jobs and bucket sync, which have no git equivalent in this material at all.
Licence, maintenance and upgrade cost
The repository is Apache-2.0 and is not archived, with the last push recorded at 2026-09-10. Apache-2.0 is a permissive licence with an explicit patent grant, which is the usual reason teams pick it over MIT for infrastructure dependencies. It also carries notice and attribution obligations when you redistribute the package or a derivative, so check how your distribution handles third-party notices. This is a description of the licence text, not legal advice; read the LICENSE file and talk to counsel if you are shipping a product. On maintenance, the weekly release rhythm visible in v1.29.0 through v1.31.0 is the cost you are signing up for. Each release note covers a mixed bag: v1.31.0 mentions custom labels for Sandboxes and more resilient downloads, v1.30.0 mentions scheduled job filters and repo-aware revision pinning, v1.29.0 mentions Xet download rate limits, bucket visibility updates and security fixes. Security fixes in a client that handles tokens is a reason to stay current rather than pin and forget. The practical upgrade path is to pin an exact version, read the release notes for the versions between your pin and the target, and re-run whatever exercises your download and upload paths before bumping.
Editorial conclusion
Adopt huggingface_hub if your code already lives on huggingface.co: the hf CLI covers login, download, upload, bucket sync and Jobs from one binary, and the Python library exposes the same surface for scripts and training loops. Do not adopt it if you only need to fetch a single public file over HTTPS, since an HTTP client and a URL do that without adding a dependency. Before rolling it out, verify three things against your own environment: which optional extras your code path imports, whether your CI can supply a token through the HF_TOKEN environment variable instead of an interactive login, and whether the revision you pin still resolves against the Hub API your release targets.
Community notes