huggingface_hub: the hf CLI and Python client for the Hugging Face Hub

What huggingface_hub actually solves

The Hub is a hosting platform for models, datasets and Spaces. Without a client, using it means hand-writing HTTP calls against its API, handling ranged downloads for multi-gigabyte weight files, dealing with resumable transfers when a connection drops, and reimplementing token authentication. huggingface_hub exists to remove that work. The README describes it as the official CLI and Python client for the Hub, and the task list is explicit: download files, upload files, manage repositories, run inference on deployed models, run Jobs on Hugging Face infrastructure, search models and datasets, publish model cards, and open pull requests and comments.

The audience is narrower than the tagline suggests. If you train or fine-tune models in Python and want to publish them, this is the package that does it. If you consume pretrained weights in a script, this is what fetches them. The CLI half matters to a different group: people who want to move files from a shell, or agents that drive a terminal rather than import a library. The README states the CLI is designed so that the same commands adapt their output when run by an agent, which is a deliberate choice rather than an afterthought.

One package, two interfaces, one token

The distribution ships both surfaces. Installing the Python package also installs the hf CLI, and the README points at pip and uv as the two supported routes. Underneath, the client talks to the Hub over HTTP using httpx, with click providing the command-line layer. Authentication is token-based: the README links to the Hub security-tokens documentation and shows hf auth login as the interactive path, with --token $HF_TOKEN offered for non-interactive environments such as CI.

File transfer is where the design gets more interesting. The setup.py lists hf-xet as a conditional dependency, pinned to hf-xet>=1.5.2,<2.0.0 and installed only on x86_64, amd64, AMD64, arm64 and aarch64 machines. That means the transfer backend is not uniform across a fleet: an ARM64 Linux runner and an x86_64 laptop both get it, an architecture outside that list does not. The repository's pytest configuration makes the same split visible in testing, with xet and no_xet markers and a stated policy that unmarked tests must pass with and without hf_xet installed. The v1.29.0 release notes mention fixing Xet download rate limits, which confirms this path is under active change. The README does not document a rollback procedure for a failed Xet transfer, so plan for that gap if large downloads are on your critical path.

Installing huggingface_hub and running a first download

Two install routes are documented. The CLI has a standalone installer that does not require Python tooling first, and the Python package brings the CLI along with it. The README gives both commands verbatim.

curl -LsSf https://hf.co/cli/install.sh | bash

On Windows the README uses a PowerShell one-liner instead. For the library, install from PyPI, or use uv if you already have it.

pip install huggingface_hub

The README notes that optional dependencies are kept out of the default install. The mcp extra is the example given, installed as a bracketed extra.

pip install "huggingface_hub[mcp]"

Once installed, log in. In a terminal you can run the interactive form; in CI, pass a token instead.

hf auth login

The README's quick start then walks through the common operations in sequence: list models served by Inference Providers, download a model, upload files to a repository you own, sync a local folder to a storage bucket, and run a job on Hugging Face infrastructure. The download command is the one most people run first.

hf download Qwen/Qwen3-0.6B

That fetches the named repository's files into the local cache. Uploading goes the other direction and takes a local path plus a target repository.

hf upload username/my-cool-model ./model.safetensors

If you are working inside a coding agent rather than a shell, the README documents a skill installation step that generates a command reference from the installed CLI, with a --claude flag for Claude Code. Everything else is discoverable through hf --help, which the README lists as the final quick-start entry.

Where the client stops being the right tool

The dependency list is not small. setup.py pulls in click, filelock, fsspec, httpx, packaging, pyyaml, tqdm and typing-extensions, plus tomli on Python versions below 3.11, plus hf-xet on the supported architectures. If you want to fetch a single config file from the Hub inside a minimal container, that is a lot of surface area for one HTTP GET, and a plain request against the API is a defensible choice.

The Xet split is the sharper edge. Because hf-xet is installed conditionally on platform_machine, two machines running the same pinned version of huggingface_hub can take different transfer paths. The test suite acknowledges this by requiring unmarked tests to pass in both configurations, and the v1.29.0 notes about Xet download rate limits show the path is still being tuned. The README does not state what happens when a Xet transfer fails partway, so treat large-download reliability as something you verify on your own hardware rather than something the documentation guarantees.

There is also a scope question. The package covers the Hub and only the Hub. If your weights live in an internal registry, an S3 bucket, or a vendor's own distribution channel, nothing here helps, and the fsspec dependency does not turn it into a general remote-filesystem tool. It is a client for one platform.

How it compares to git-lfs and plain HTTP

The obvious alternative for moving model files is git with Git LFS, which is how Hub repositories were historically cloned. The difference in approach is structural. Git LFS tracks large files through a pointer mechanism inside a Git repository, so a clone brings history, refs and the pointer files along with the weights. huggingface_hub skips Git for the common cases: hf download fetches the files you asked for, and hf upload pushes a local path to a repository without requiring a working tree. For a CI job that needs one safetensors file, that is the difference between a shallow clone plus LFS fetch and a single command.

The second alternative is calling the Hub's HTTP API directly. That gives you full control over retries, concurrency and caching, and it removes the dependency tree entirely. The cost is that you reimplement authentication, resumable downloads and the repository operations the client already exposes, and you track Hub API changes yourself. huggingface_hub is the maintained layer for exactly that work, which is why the README frames it as the official client. If your needs are genuinely one endpoint and one file, direct HTTP is simpler; if you touch uploads, repository management or Jobs, the client is doing more than you would want to write.

Maintenance, releases and what Apache-2.0 means here

The repository is not archived. The last push was on 2026-09-10, and releases are frequent: v1.31.0 on 2026-09-10, v1.30.0 on 2026-09-03, and v1.29.0 on 2026-08-27. That cadence cuts both ways for adopters. You get fixes quickly, including the security fixes listed in the v1.29.0 notes, but you also get a moving target. Pinning a version in requirements or a lockfile is the practical response, and the project's own strict dependency bounds (click>=8.4.2,<9.0.0, httpx>=0.23.0,<1) suggest the maintainers already think in those terms.

The licence is Apache-2.0, which permits commercial and closed-source use and includes an explicit patent grant. It is a permissive licence, not a copyleft one, so it does not oblige you to publish modifications. That is a statement about the licence text, not legal advice; if you are redistributing the package or embedding it in a product with unusual compliance requirements, have your own counsel read it.

Upgrade cost is mostly about the CLI surface. The repository contains a generated CLI reference, produced by a script in the Makefile, so command documentation tracks the code rather than drifting from it. The flip side is that CLI behaviour can change between minor versions, and the release titles show feature work landing weekly. Read the release notes before bumping, particularly for anything touching downloads or the Xet path.

Editorial conclusion

Adopt huggingface_hub if your models, datasets or Spaces already live on the Hub and you want one package that covers downloads, uploads, repository management and Jobs from both Python and the terminal. Skip it if your artifacts sit in an internal registry or object store and nothing in your pipeline reads from huggingface.co, because the client only earns its place when the Hub is in the loop. Before rolling it out, verify three things: whether hf_xet is installed on your target machines, since it is pulled in conditionally by platform_machine, whether your CI can supply HF_TOKEN instead of an interactive hf auth login, and whether your pinned version still matches the CLI reference the docs describe.

Frequently asked questions

Official sources

1. huggingface/huggingface_hub on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases