What's new in the hf CLI and huggingface_hub library

We've been shipping a lot of features in huggingface_hub/hf CLI these past few weeks across Hugging Face Jobs, Storage Buckets, Sandboxes, cache optimization, DX improvements for downloading and uploading and more. Here is a recap of the highlights.

Shared cache: download each file once across repos

The same file often lives in many repos. For example, FLUX.1-dev, FLUX.1-schnell and FLUX.1-Krea-dev all ship the same 9.5 GB text encoder. Your cache now stores each Xet file once, and other repos that need it get a link instead of a new download: no bytes transferred, no extra disk used. There is nothing to configure.

Cleaning up got easier too. You can remove a single cached file, like one GGUF quantization, without deleting the whole repo, and hf cache prune removes shared files that no repo uses anymore:

hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf
hf cache prune

Hugging Face Jobs: retries, reruns and UV script config

Jobs got many small upgrades that add up:

hf jobs run --attempts 3 python:3.12 python train.py   # retry on failure
hf jobs rerun <job_id>                                  # same secrets and hardware
hf jobs scheduled reschedule <id> "0 9 * * *"           # change the schedule
hf jobs expose <job_id> 8000 --public 9000              # open ports on a running job
hf jobs scheduled ls --status suspended --label env=prod

Every Job now gets a name automatically, from its image or script and a short hash of the command, so reruns of the same command are easy to find.

A UV script can also carry its own Job config, in a [tool.hf-jobs] table of its header. hf jobs uv run picks it up, so the script always runs on the right image and hardware. Flags you pass on the command line still win.

A webhook can also start a Job instead of calling a URL. Each time a repo or a Storage Bucket you watch changes, the Job runs again, with the event in the WEBHOOK_PAYLOAD environment variable. Webhooks can now watch Storage Buckets, and pass secrets like your HF_TOKEN to the Job, so it can read and write on the Hub:

hf webhooks create --job-id <job_id> --watch bucket:my-org/raw-data --secrets HF_TOKEN

<job_id> is a Job you ran before: each event starts a new Job with the same setup. --secrets HF_TOKEN passes the token you are logged in with.

Jobs commands also behave better in scripts and agents: hf jobs stats prints a snapshot and exits (add -f to follow), hf jobs logs without -f no longer hangs, and hf jobs run reconnects when the log stream drops. In your terminal, it also shows why a Job is still waiting for hardware.

Storage Buckets: faster downloads and live listings

Downloading data from a Storage Bucket is much faster: HfFileSystem now downloads Xet files with hf_xet, straight to disk. In our benchmark on HF Jobs, downloading a 2.15 GB parquet file went from 2 minutes to about 7 seconds.

from huggingface_hub import HfFileSystem

fs = HfFileSystem()
fs.get("buckets/my-org/my-bucket/train.parquet", "train.parquet")

The datasets library reads hf:// paths through HfFileSystem, so load_dataset gets the same speedup starting with datasets 5.1.0, the first release that works with huggingface_hub 2.x. Loading the same file went from 130 seconds to about 17.

from datasets import load_dataset

ds = load_dataset("parquet", data_files="hf://buckets/my-org/my-bucket/train.parquet")

HfFileSystem caches listings, so files added to a Storage Bucket by another process used to stay invisible until you cleared the cache. With live_follow=True, listings update as new files land.

from huggingface_hub import HfFileSystem

fs = HfFileSystem(live_follow=True)
fs.ls("buckets/my-org/training-run")

You can also set a Storage Bucket's visibility when you create it, or change it later with hf buckets settings my-org/my-bucket --public.

Sandboxes: run code in isolated cloud machines

Sandboxes (experimental) are isolated machines that you start from Python or the CLI, run commands in, and move files in and out of. They run on Jobs, so any Docker image works, on CPU or GPU. This is useful when an agent needs to run code it just wrote, away from your laptop.

hf sandbox create --label controller-run=run-42
hf sandbox exec <id> -- python -c "print('hi')"
hf sandbox kill <id>

Recent releases added custom labels, to find the sandboxes a run created or track costs, and a round of security hardening.

📚 Sandboxes guide

Benchmarking the hf CLI skill for AI agents

AI agents are now a big part of who uses the hf CLI. On a given day, 1 in 3 users of the hf CLI is an AI agent. For uploads, more than half of the users who upload to the Hub with the hf CLI do it through an AI agent.

The hf-cli skill makes them faster, not more accurate. Recent models already know a lot about the hf CLI and find their way with hf --help, so they solve Hub tasks just as well without the skill. With it, they skip the trial and error. We ran DeepSeek-V4.1-Flash and Kimi-K3 through Hugging Face Inference Providers on 28 Hub tasks, with and without the skill.

Both models solved 99 to 100% of the tasks either way, but with the skill they needed about a third fewer turns and almost stopped calling --help.

More DX improvements for downloads, uploads and ZeroGPU

Downloads and uploads got smoother:

• hf download no longer makes one API call per file, which used to hit rate limits on repos with tens of thousands of files.
• Parallel downloads always use hf_xet, instead of sometimes falling back to plain HTTP.
• hf download warns you when your --include or --exclude patterns match no files.
• Very large uploads show a "Validating" progress bar at the end, instead of going quiet.
• from huggingface_hub import * is 6× faster: 0.39 seconds instead of 2.36.

You can also check how much ZeroGPU time you have left, from the CLI or in Python. Apps and agents built on ZeroGPU Spaces can use it to warn users before they hit the daily limit.

$ hf spaces zero-gpu quota
✓ ZeroGPU quota (in GPU-seconds)
  remaining: 1810
  base: 2400
  resets_at: 2026-09-30T18:12:03+00:00
  overquota_used: 0

>>> from huggingface_hub import get_zero_gpu_quota
>>> get_zero_gpu_quota().remaining
1810

Get the latest version

Ask your agent to upgrade the hf CLI to the latest version or run hf update yourself. All the details are in the release notes.