TL;DR
On April 24, 2026, huggingface_hub v1.12.0 landed with two changes that punch above their version number. First, every hf buckets subcommand now speaks the same output language: a single --format [auto|human|agent|json|quiet] flag replaces the old patchwork of --quiet and --format table|json. Second, you can finally search buckets by name on the server with list_buckets(search=...) or hf buckets list --search — no more listing everything and grepping locally.
Smaller fixes shipped too: HfFileSystem fsspec config now applies via metaclass, download sync without --delete got a faster local walk, and ExpandDatasetProperty_T gained a mainSize property. Lucain Wauplin walks through the highlights on X.
What's new
Two headline features and a handful of polish items.
- Unified
--formatflag onhf buckets create,list,info,delete/rm,move, andcp. Five values:auto(TTY-aware default),human(tables and readable text),agent(structured-but-text, tuned for LLM agents),json(raw JSON forjqpiping), andquiet(one ID per line). - Server-side bucket search:
list_buckets(search="checkpoint")in Python and--search "checkpoint"on the CLI. - Spaces hot-reload improvements and a new "pi" agent detection capability.
- Internal: dev version bumped to
1.12.0.dev0; the release workflow now also drafts a Slack message and social posts.
Seven contributors landed this one — Wauplin, hanouticelina, abidlabs, alexpouliquen, cbensimon, rtrompier, and joaquinhuigomez.
Why it matters
If you only use the Hub through the web UI, this is a non-event. If you script against it, both changes remove paper cuts you've probably been working around.
The unified --format matters because every CLI tool that grew organically eventually develops flag rot: --quiet on one subcommand, --format json on another, neither on a third, and the docs are the only way to remember which is which. Collapsing six commands onto one consistent set of values means muscle memory transfers, and the new agent mode is a quiet acknowledgment that LLM agents are now first-class CLI consumers — they need parseable output that's cheaper than full JSON.
Server-side --search sounds boring until you've got an org with hundreds of buckets — one per training run, one per logs bundle, one per intermediate dataset. Listing them all to find run-2026-04-* was N round trips of pagination plus a local grep. Now it's one request.
Technical facts
Quick reference for the new flags:
| Format | What you get | Use it for |
|---|---|---|
auto | Picks human on TTY, json when piped | Default — usually right |
human | Formatted tables and readable text | Interactive terminal use |
agent | Structured plain text, tuned for LLM parsing | Claude/GPT-driven workflows |
json | Raw JSON arrays/objects | Piping to jq, CI/CD scripts |
quiet | One ID per line, nothing else | Piping to xargs, batch ops |
Internally the migration introduces three output helpers: out.result() for success messages, out.dict() for object details, and out.table() for tabular listings. Every migrated subcommand now routes through the same singleton instead of printing ad hoc.
Comparison: before vs. after
Listing buckets in a busy namespace, before v1.12.0:
hf buckets list --quiet | grep "^username/run-2026-04"
hf buckets list --format json | jq '.[] | select(.id | startswith("username/run-2026-04"))'After v1.12.0:
hf buckets list username --search "run-2026-04" --format quietOne round trip, no client-side filtering. For comparison, AWS's aws s3 ls still has no server-side bucket search — you list every bucket and pipe to grep. GCS's gsutil filters by prefix but on object keys, not bucket names. HF lands closer to what you actually want for many-bucket workflows.
Use cases
Where the new ergonomics show up most:
- CI/CD enumerating buckets —
--format jsonpiped tojqis now a stable contract across everyhf bucketscommand, not a per-subcommand quirk. - LLM-driven tooling — agents that shell out to
hfsave tokens by using--format agentinstead of either dense JSON or pretty tables. - Researchers with hundreds of checkpoint buckets —
hf buckets list --search "run-04"beats listing the whole namespace. - Batch ops via
xargs—hf buckets list --search "old-" --format quiet | xargs -I {} hf buckets delete {} --yes.
Limitations & pricing
The Python client is Apache 2.0 and free. Buckets are part of Hugging Face's Xet storage backend, so storage quotas follow your account tier (free community tier, Pro, Team, Enterprise). A few sharp edges to know about:
--searchfilters on bucket names only — it does not search inside the files of a bucket.- Bucket-to-repo copy is still not supported.
batch_bucket_files()remains non-transactional — partial failures can leave you in a mixed state.- The
agentoutput format is new and explicitly may evolve; don't pin scripts to its exact shape yet. - No breaking changes:
--quietand--format jsonstill work where they did before. The new--formatis additive.
What's next
Reading between the lines of recent PRs and dev notes, the obvious next steps are: rolling the unified --format out to the rest of the CLI (hf cache, hf jobs, hf endpoints already partially support JSON output but with their own conventions), expanding server-side filters beyond name (size, date, privacy), and promoting the agent format from experimental to a documented contract once usage settles. Spaces hot-reload also got a touch this release — expect more iterations.
To upgrade:
pip install -U huggingface_hub
# or always use the latest in an isolated env
uvx hf --versionSources: v1.12.0 release notes, Hugging Face Buckets guide, Wauplin on X.