releases.shpreview
Home/Hugging Face/Hub

Hub

Python client for the Hugging Face Hub API

v1.16.0

↗
Token files hardened to 0o600; Together adds embeddings, TTS, ASR, video

⚡ Together goes multimodal on Inference Providers

Together now supports five additional task types beyond chat and text-to-image on Inference Providers:

  • feature_extraction
  • text_to_speech
  • automatic_speech_recognition
  • image_to_image
  • text_to_video
from huggingface_hub import InferenceClient

client = InferenceClient(provider="together")

# Embeddings
embeddings = client.feature_extraction("Hello world", model="intfloat/multilingual-e5-large-instruct")

# Text-to-speech
audio = client.text_to_speech("Hello world", model="hexgrad/Kokoro-82M", extra_body={'voice': 'af_heart'})

# Text-to-video
video = client.text_to_video("A cat on the moon", model="Wan-AI/Wan2.2-T2V-A14B")
  • [Inference] Add embeddings, TTS, ASR, image-to-image and video tasks for Together by @nbroad1881 in #4164

📚 Documentation: Inference guide

🔗 Centralized hf:// URI parsing

All scattered ad-hoc hf:// URI parsers throughout the codebase have been consolidated onto the new parse_hf_uri/parse_hf_mount helpers. This brings consistent parsing behavior, a new is_hf_uri public helper for validating URIs, and proper handling of @ in filenames (now treated as literal). The CLI error handler now catches HfUriError and displays a clean message instead of a raw traceback.

🚨 Breaking Changes

This migration includes several breaking changes: BucketUrl.handle has been renamed to BucketUrl.uri (type changed from str to HfUri, use .to_uri() for the string form), Volume.to_hf_handle() has been renamed to Volume.to_uri(), single-segment repo IDs (e.g. gpt2) are no longer supported in HfFileSystem paths or CLI -v flags — you must use the namespace/name format instead.

  • [Core] Migrate hf:// URI parsing to centralized parse_hf_uri by @Wauplin in #4189

📚 Documentation: CLI guide | Buckets guide

🖥️ CLI

Global --no-truncate flag for CLI tables

A new --no-truncate global formatting flag disables the ... shortening of scalar values in human-mode tables, letting you see full IDs, names, and other long text at a glance. List- and dict-valued columns (e.g. tags) remain shortened in human mode since they can be arbitrarily long; use --format json for those. When any cell is truncated, human tables now print a one-line hint at the bottom pointing you to the right flag.

# Show full scalar values in table output
hf models ls --no-truncate
  • [CLI] Add global --no-truncate flag for human tables by @hanouticelina in #4229

📚 Documentation: CLI guide

Miscellaneous
  • [CLI] Surface job runtime fields in ps + inspect by @davanstrien in #4211
  • [CLI] Parse initiator field on jobs API responses by @davanstrien in #4212
  • [CLI] Support hf:// URIs in cache rm by @abhinavgautam01 in #4235
  • [CLI] Expose linked repos in PaperInfo by @mishig25 in #4240
  • [CLI] Raise error when both --local-dir and --cache-dir are provided by @Wauplin in #4245

🔒 Token file permissions hardened

Token files written by huggingface_hub (~/.cache/huggingface/token and ~/.cache/huggingface/stored_tokens) were previously created with Python's default modes, leaving them world-readable on most systems. This PR sets file permissions to 0o600 and parent directory permissions to 0o700 after every write, bringing huggingface_hub in line with industry-standard tools like GitHub CLI, AWS CLI, and Google Cloud SDK. Pre-existing installations will converge to safe permissions on the next token save. The chmod calls are wrapped in try/except for Windows, which doesn't support POSIX modes.

  • [Auth] Harden HF_TOKEN_PATH and HF_STORED_TOKENS_PATH to 0o600 / 0o700 by @JAE0Y2N in #4234

📊 Jobs

  • Use server-side support to tail job logs by @coyotte508 in #4202
  • [Jobs] Add ephemeral_storage field to JobHardware by @Wauplin in #4233

🐛 Bug and typo fixes

  • [Download] Fix snapshot bar inflation on http_get retry by @popfido in #4209

📖 Documentation

  • [Docs] Refresh contributing guide and README by @Wauplin in #4237

🏗️ Internal

  • Post-release: bump version to 1.16.0.dev0 by @huggingface-hub-bot[bot] in #4230
  • Fix catch-all empty string in CI pytest --only-rerun by @albertvillanova in #4239
  • [Internal] Silence ty invalid-type-form on WebhooksServer annotations by @hanouticelina in #4242
  • [CI] make test_model_info_with_security for robust by @Wauplin in #4246

v1.15.0

↗
Pick region when creating buckets/repos; `hf skills list` discovers marketplace skills

🌍 Pick a region when creating buckets and repos

create_bucket and create_repo now accept an optional region argument ("us" or "eu") so you can pin a new bucket or repo to a specific cloud region at creation time. The same option is exposed on the CLI via a --region flag on hf buckets create and hf repos create.

>>> from huggingface_hub import create_bucket, create_repo
>>> create_bucket("my-bucket", region="us")
>>> create_repo("my-model", region="eu")
$ hf buckets create my-bucket --region us
$ hf repos create username/my-model --region eu
  • [Bucket/Repo] Support 'region' option in create_bucket and create_repo by @Wauplin in #4194

🧩 Discover marketplace skills with hf skills list

A new hf skills list (alias ls) command lists every skill available in the Hugging Face marketplace and shows whether each one is already installed in the four supported locations (project, global, project Claude, global Claude). Handy when you want to check what's installable and what you've already got before running hf skills add.

$ hf skills ls
NAME                        DESCRIPTION                         PROJECT PROJECT (CLAUDE) GLOBAL GLOBAL (CLAUDE)
--------------------------- ----------------------------------- ------- ---------------- ------ ---------------
hf-cli                      Execute Hugging Face Hub operati...     yes              yes    yes             yes
  • [CLI] Add hf skills list command by @Wauplin in #4180

🎨 Polished --help output with ANSI styling

hf --help and every subcommand now render with underlined section headings and bold option/command names, making the help screens much easier to scan in a terminal. The new styling is automatically disabled when NO_COLOR is set or when the CLI detects it's running under an AI agent, so script and agent output stays clean.

  • [CLI] Pretty-print --help with ANSI styling by @Wauplin in #4192

🖥️ CLI

  • [CLI] Check Homebrew registry for updates when installed via brew by @Wauplin in #4204 — hf update no longer suggests a version that isn't on brew yet for Homebrew installs.
  • [CLI] No traceback on LocalEntryNotFoundError by @Wauplin in #4190 — offline/cache-miss errors now print a clean message instead of a Python traceback (set HF_DEBUG=1 for the full stack).

🐛 Bug and typo fixes

  • Make HF_HUB_ENABLE_HF_TRANSFER deprecation warning visible to users by @Adithya191101 in #4220
  • Fix hint message to use 'hf skills update' by @Pierrci in #4206

📖 Documentation

  • [docs] Drop duplicated Key Features list from hf jobs CLI section by @davanstrien in #4222

🏗️ Internal

  • [CI] Harden style-bot workflow against TOCTOU by @paulinebm in #4183
  • Only sync skill if SKILL.md has changed by @evalstate in #4210

v1.14.0

↗
[v1.14.0] Handle Spaces secrets & variables from CLI and other improvements

🖥️ Manage Space secrets and variables from the CLI

You can now manage Space secrets and environment variables directly from the command line with two new hf spaces subgroups: secrets and variables. Use hf spaces secrets to add, list, and delete write-only secrets, and hf spaces variables to add, list, and delete readable environment variables. Both add commands support multiple -s/-e flags and --secrets-file/-env-file for loading from dotenv files. On the Python side, HfApi.get_space_secrets() returns secret metadata (key, description, updated timestamp) without ever revealing values.

# List secrets (values are write-only — only keys and timestamps are shown)
$ hf spaces secrets ls username/my-space

# Add secrets
$ hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...
$ hf spaces secrets add username/my-space --secrets-file .env.secrets

# Delete a secret (confirmation prompt, use --yes to skip)
$ hf spaces secrets delete username/my-space OPENAI_API_KEY --yes

# List, add, and delete variables (values are readable)
$ hf spaces variables ls username/my-space
$ hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512
$ hf spaces variables delete username/my-space MAX_TOKENS --yes
  • [CLI] Add hf spaces secrets and variables subgroups by @davanstrien in #4170
  • [CLI] Add get_space_secrets + hf spaces secrets ls by @Wauplin in #4182

📚 Documentation: CLI guide · Manage your Space

🪣 Rsync-style trailing slash for bucket folder copies

hf buckets cp now supports rsync-style trailing slash semantics when copying folders. A trailing / on the source path copies only the folder's contents to the destination, while omitting it nests the folder itself — matching the behavior you'd expect from rsync. This makes it possible to flatten directory structures during copies, which was not possible before. Additionally, copy_files now raises an explicit EntryNotFoundError when the source path resolves to no files, instead of silently succeeding with zero operations.

# Without trailing slash: "logs" dir is nested => dst/logs/...
$ hf buckets cp hf://buckets/username/src-bucket/logs hf://buckets/username/dst/

# With trailing slash: only contents of "logs" are copied => dst/...
$ hf buckets cp hf://buckets/username/src-bucket/logs/ hf://buckets/username/dst/
  • [Buckets] Support rsync-style trailing slash in copy_files by @Wauplin in #4187
  • [CLI] Raise error when copy_files source doesn't exist by @Wauplin in #4186

📚 Documentation: Buckets guide · CLI guide

💔 Breaking Change

  • [CLI] Rename hf skills upgrade -> hf skills update by @hanouticelina in #4176 — hf skills upgrade no longer exists; use hf skills update instead.
  • [CLI] Add out.status() by @hanouticelina in #4171 — status updates (spinners/progress) on hf extensions install and hf spaces dev-mode are now suppressed when using --format json, --quiet, or --format agent.

🖥️ CLI

  • [CLI] Add hints and example to hf datasets leaderboard by @Wauplin in #4174
  • [CLI] Shortcut hf update when already on latest version by @julien-c in #4177
  • [CLI] Remove progress bars on skills update by @Wauplin in #4179
  • [CLI] Increase default --limit from 10 to 30 for list commands by @Wauplin in #4181
  • [CLI] Support hf -v to print version by @Wauplin in #4185
  • [CLI] migrate hf skills to bucket by @hanouticelina in #4175

🐛 Bug and typo fixes

  • Update typer dependency version in setup.py by @tomaarsen in #4193

🏗️ Internal

  • Post-release: bump version to 1.14.0.dev0 by @huggingface-hub-bot[bot] in #4172
  • [Release] Move social drafts to minor-release and archive release notes to bucket by @Wauplin in #4173
  • Update unit test warnings check to ignore unrelated deprecation warnings by @seanses in #4188
  • [internal] Untrack useless files by @Wauplin in #4191

v1.13.0

↗
[v1.13.0] new CLI commands and formatting, and HF URI parsing

🖥️ New CLI commands: repo cards, file listings, and dataset leaderboards

This release adds three new CLI capabilities for exploring Hub content. hf models card, hf datasets card, and hf spaces card fetch the README of any repo and print it to stdout, with --metadata (YAML frontmatter as JSON) and --text (prose only) flags for splitting the card into its structured and unstructured parts. Calling hf models ls <repo_id>, hf datasets ls <repo_id>, or hf spaces ls <repo_id> now switches from listing repos to listing files inside that repo, with --tree, -R, -h, and --revision options mirroring the existing hf buckets ls behavior. And hf datasets leaderboard <dataset_id> surfaces model scores submitted to a benchmark dataset, making it easy to compare models by score from the terminal.

# Get model card metadata as JSON
hf models card google/gemma-4-31B-it --metadata --format json

# List files in a model repo (tree view with sizes)
hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h

# Show top 5 models on SWE-bench
hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5

📚 Documentation: CLI guide

  • [CLI] Add hf models card and hf datasets card commands by @davanstrien in #4118
  • [CLI] Add file listing to models/datasets/spaces ls by @Wauplin in #4166
  • [CLI] add hf datasets leaderboard by @hanouticelina in #4154

🚀 Manage Spaces from the CLI

Three new hf spaces subcommands bring full lifecycle control to the terminal. hf spaces pause and hf spaces restart stop or rebuild a Space (with --factory-reboot for a clean rebuild), and hf spaces settings lets you configure sleep time and hardware in one call. A companion hf spaces hardware command lists all available hardware flavors with pricing, so you can discover options before changing settings. Pause and restart include a confirmation prompt (-y to skip) since they tear down the running container.

# Pause a Space when not in use (not billed while paused)
hf spaces pause username/my-space

# Restart with a GPU
hf spaces settings username/my-space --hardware t4-medium --sleep-time 3600

# List available hardware options
hf spaces hardware

📚 Documentation: CLI guide — Spaces

  • [CLI] Add spaces lifecycle commands: pause, restart, sleep by @davanstrien in #4155
  • [CLI] Add hf spaces hardware command by @Wauplin in #4169
  • [CLI] Add --hardware flag to hf spaces settings by @davanstrien in #4163

🔃 hf update replaces the auto-update prompt

The blocking interactive Y/n auto-update prompt at CLI startup is gone. It was catching too many non-interactive contexts (CI runners, Homebrew post-install hooks, Jupyter notebooks) and hanging automation. In its place, a single yellow stderr warning suggests running hf update — a new command that detects how hf was installed (Homebrew, standalone installer, or pip) and runs the right upgrade command. Set HF_HUB_DISABLE_UPDATE_CHECK=1 to silence the startup check entirely, for example in offline CI.

hf update

📚 Documentation: CLI guide — Updating

  • [CLI] Add hf update + drop interactive update prompt by @Wauplin in #4131

✏️ Global output formatting for every command

The --format, --json, and -q / --quiet flags are now handled globally by the CLI framework instead of being declared individually on each command. This means every hf command automatically accepts them — no more per-command --format boilerplate, and the flags are properly documented in a dedicated "Formatting options" section in every --help page. --format auto (the default) picks human for interactive terminals and agent when invoked by an AI agent, making CLI output automatically suitable for both people and tools.

# JSON output for scripting
hf models ls --search bert --limit 2 --json | jq '.[].id'

# IDs only, one per line
hf collections ls --owner nvidia -q

📚 Documentation: CLI guide — Output formatting

  • [CLI] Make --format / --json / -q global by @Wauplin in #4162

🔗 Centralized hf:// URI parsing

A new parse_hf_uri function and HfUri dataclass provide a single source of truth for parsing hf://... strings across the library. Whether you reference a model, dataset, space, bucket, or file inside a repo, the parser handles all valid URI shapes — type prefixes, revisions, and paths — and rejects invalid ones with clear error messages. A companion parse_hf_mount / HfMount handles volume mount specifications (hf://...:/mnt:ro). Both are pure string parsers (no network calls) and round-trippable via .to_uri().

from huggingface_hub import parse_hf_uri, parse_hf_mount

parse_hf_uri("hf://datasets/namespace/my-dataset@refs/pr/3/train.json")
# HfUri(type='dataset', id='namespace/my-dataset', revision='refs/pr/3', path_in_repo='train.json')

parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:ro")
# HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', ...), mount_path='/mnt', read_only=True)

📚 Documentation: HF URIs reference

  • Centralize hf:// URI parsing by @Wauplin in #4158

🚀 Bucket transport for Jobs script upload

Local scripts uploaded by hf jobs uv run are now stored in a {namespace}/jobs-artifacts bucket and mounted into the job container at /data instead of being base64-encoded into an environment variable. The old bash -c + xargs + base64 -d pipeline was fragile and required manual shell quoting. Bucket transport is simpler, easier to debug, and supports write-back: jobs can persist output artifacts to /data/ since the mount is read-write. The base64 transport path has been fully removed with no fallback.

  • Add bucket+mount transport for Jobs script upload by @davanstrien in #4025

🖥️ CLI

  • [CLI] Print help when leaf command with required args is called without args by @Wauplin in #4135

🤖 Inference

  • [Inference Providers] Add DeepInfra support by @hanouticelina in #4114
  • Support list[str] inputs in feature_extraction by @SJeffZhang in #4115

📖 Documentation

  • [CLI] Add benchmark dataset filter examples by @hanouticelina in #4156

🐛 Bug and typo fixes

  • [BUG FIX]: hf_hub_download crashes when stderr lacks a real file descriptor by @tobocop2 in #4065
  • [CLI] Fix datasets list table rendering by @hanouticelina in #4157
  • [CLI] Fix installation method detection for curl-installed hf with Homebrew Python by @Wauplin in #4142
  • Avoid reuploading preuploaded LFS files in upload-large-folder by @Dev-Jahn in #4165

🏗️ Internal

  • [Release] Make release-notes job fail loudly on bad model/empty output by @Wauplin in #4138
  • [Release] Fix bucket URL in social posts Slack notification by @Wauplin in #4139
  • Post-release: bump version to 1.13.0.dev0 by @huggingface-hub-bot[bot] in #4140
  • [CI] Fix two flaky Windows tests (root causes, not skips) by @Wauplin in #4141
  • [Quality] Fix uvx ty check src errors by @Wauplin in #4159
  • [Release] Mark minor releases as "latest" on GitHub by @Wauplin in #4167

v1.12.0

↗
[v1.12.0] Unified CLI output, bucket search, and more

🖥️ Unified output format for hf buckets commands

All hf buckets commands now use the unified --format [auto|human|agent|json|quiet] flag and the out singleton for consistent, scriptable output. The previous --quiet and --format table|json flags have been replaced by a single --format option that works across create, list, info, delete, rm, move, and cp. Success messages use out.result(), detail views use out.dict(), and listings use out.table() with proper empty-results handling — making the buckets CLI consistent with the rest of the hf command suite.

# Quiet mode: print only bucket IDs
hf buckets list --format quiet

# JSON output for scripting
hf buckets create my-bucket --format json

# Agent-friendly structured output
hf buckets info username/my-bucket --format agent
  • [CLI] Migrate buckets commands to out singleton by @hanouticelina in #4111

📚 Documentation: Buckets guide · CLI guide

🪣 Search buckets by name

You can now filter buckets by name when listing them, both from the Python API and the CLI. Pass search="checkpoint" to list_buckets() or --search "checkpoint" to hf buckets list to find buckets matching a name pattern, without having to list and filter client-side.

# Filter buckets by name
hf buckets list --search "checkpoint"
# Filter buckets by name in Python
for bucket in list_buckets(search="checkpoint"):
    print(bucket.id)
  • [Buckets] Add search param to list_buckets by @alexpouliquen in #4130

📚 Documentation: Buckets guide · CLI guide

🖥️ CLI

🐛 Bug and typo fixes

🔧 Other QoL Improvements

  • [Buckets] Skip local walk for download sync without delete by @abidlabs in #4123
  • [HfApi] Add mainSize to ExpandDatasetProperty_T by @Wauplin in #4136

🏗️ Internal

  • [Internal] Fix slack-message draft release permissions + update model by @hanouticelina in #4119
  • Post-release: bump version to 1.12.0.dev0 by @huggingface-hub-bot[bot] in #4120
  • [Internal] Make RELEASE_NOTES_MODEL configurable via repo variable by @Wauplin in #4126
  • [Release] Add social media draft generation to release workflow by @Wauplin in #4132
  • chore: bump doc-builder SHA for main doc build workflow by @rtrompier in #4137
  • [Release] Make release-notes job fail loudly on bad model/empty output by @Wauplin in #4138

v1.11.0

↗
[v1.11.0] Semantic Spaces search, Space logs, and more

🔍 Semantic search for Spaces

Discover Spaces using natural language. The new search_spaces() API and hf spaces search CLI use embedding-based semantic search to find relevant Spaces based on what they do - not just keyword matching on their name.

>>> from huggingface_hub import search_spaces

>>> results = search_spaces("remove background from photo")
>>> for space in results:
...     print(f"{space.id} (score: {space.score:.2f})")
briaai/BRIA-RMBG-1.4 (score: 0.87)

The same capability is available in the CLI:

$ hf spaces search "remove background from photo" --limit 3
ID                           TITLE                 SDK    LIKES STAGE   CATEGORY           SCORE
---------------------------- --------------------- ------ ----- ------- ------------------ -----
not-lain/background-removal  Background Removal    gradio 2794  RUNNING Image Editing      0.85 
briaai/BRIA-RMBG-2.0         BRIA RMBG 2.0         gradio 918   RUNNING Background Removal 0.84 
Xenova/remove-background-web Remove Background Web static 739   RUNNING Background Removal 0.81 
Hint: Use --description to show AI-generated descriptions.

# Filter by SDK, get JSON with descriptions
$ hf spaces search "chatbot" --sdk gradio --description --json --limit 1 | jq
[
  {
    "id": "BarBar288/Chatbot",
    "title": "Chatbot",
    "sdk": "gradio",
    "likes": 4,
    "stage": "RUNNING",
    "category": "Other",
    "score": 0.5,
    "description": "Perform various AI tasks like chat, image generation, and text-to-speech"
  }
]

📜 Programmatic access to Space logs

When a Space fails to build or crashes at runtime, you can now retrieve the logs programmatically — no need to open the browser. This is particularly useful for agentic workflows that need to debug Space failures autonomously.

>>> from huggingface_hub import fetch_space_logs

# Run logs (default)
>>> for line in fetch_space_logs("username/my-space"):
...     print(line, end="")

# Build logs — for BUILD_ERROR debugging
>>> for line in fetch_space_logs("username/my-space", build=True):
...     print(line, end="")

# Stream in real time
>>> for line in fetch_space_logs("username/my-space", follow=True):
...     print(line, end="")

The CLI equivalent:

$ hf spaces logs username/my-space              # run logs
$ hf spaces logs username/my-space --build      # build logs
$ hf spaces logs username/my-space -f           # stream in real time
$ hf spaces logs username/my-space -n 50        # last 50 lines

🖥️ CLI output standardization continues

This release continues the CLI output migration started in v1.9, bringing 11 more command groups to the unified --format flag. The old --quiet flags on migrated commands are replaced by --format quiet.

$ hf cache ls                          # auto-detect (human or agent)
$ hf cache ls --format json            # structured JSON
$ hf cache ls --format quiet           # minimal output, great for piping
$ hf upload my-model . .               # auto-detect (human or agent)

Confirmation prompts (e.g., hf cache rm, hf repos delete, hf buckets delete) are now mode-aware: they prompt in human mode, and require --yes in agent/json/quiet modes - no more hanging scripts.

Commands migrated in this release: collections, discussions, extensions, endpoints, webhooks, cache, repos, repo-files, download, upload, and upload-large-folder. Remaining commands (jobs, buckets, auth login/logout) will follow in a future release.

📦 Space volumes management from the CLI

A new hf spaces volumes command group lets you manage volumes mounted in Spaces directly from the command line — list, set, and delete using the familiar -v/--volume syntax.

# List mounted volumes
$ hf spaces volumes ls username/my-space
TYPE    SOURCE                MOUNT_PATH READ_ONLY
------- --------------------- ---------- ---------
model   gpt2                  /data      ✔
dataset badlogicgames/pi-mono /data2     ✔

# Set volumes
$ hf spaces volumes set username/my-space -v hf://buckets/username/my-bucket:/data
$ hf spaces volumes set username/my-space -v hf://models/username/my-model:/models

# Delete all volumes
$ hf spaces volumes delete username/my-space

🔧 More CLI improvements

hf auth token - Prints the current token to stdout, handy for piping into other commands:

$ hf auth token
hf_xxxx
Hint: Run `hf auth whoami` to see which account this token belongs to.

# Use it in a curl call
$ hf auth token | xargs -I {} curl -H "Authorization: Bearer {}" https://huggingface.co/api/whoami-v2

💔 Breaking change

model_name deprecated in list_models - Use search instead. Both were always equivalent (both map to ?search=... in the API), but now model_name emits a deprecation warning. Removal is planned for 2.0.

# Before
>>> list_models(model_name="gemma")

# After
>>> list_models(search="gemma")

The CLI is not affected - hf models ls already uses --search.

🔧 Other improvements

🐛 Bug fixes

📖 Documentation

🏗️ Internal

v1.10.0

↗
[v1.10.0] Instant file copy and new Kernel repo type

📁 Instant file copy between Buckets and Repositories

This release introduces server-side file copy operations that let you move data between Hugging Face storage without downloading and re-uploading. You can now copy files from one Bucket to another, from a repository (model, dataset, or Space) to a Bucket, or between Buckets — all without bandwidth costs. Files tracked with Xet are copied directly by hash (no data transfer), while small text files not tracked with Xet are automatically downloaded and re-uploaded.

>>> from huggingface_hub import copy_files

# Bucket to bucket (same or different bucket)
>>> copy_files(
...     "hf://buckets/username/source-bucket/checkpoints/model.safetensors",
...     "hf://buckets/username/destination-bucket/archive/model.safetensors",
... )

# Repo to bucket
>>> copy_files(
...     "hf://datasets/username/my-dataset/processed/",
...     "hf://buckets/username/my-bucket/datasets/processed/",
... )

The same capability is available in the CLI:

# Bucket to bucket
>>> hf buckets cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archives/logs/

# Repo to bucket
>>> hf buckets cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/

Note that copying files from a Bucket to a Repository is not yet supported.

📚 Documentation: Buckets guide

⚛️ Introducing Kernel repositories

Tip

For building, publishing, and using kernel repos, please use the dedicated kernels package.

The Hub now supports a new kernel repository type for hosting compute kernels. This release adds first-class (but explicitly limited) support for interacting with kernel repos via the Python API. Only a subset of methods are officially supported: kernel_info, hf_hub_download, snapshot_download, list_repo_refs, list_repo_files, and list_repo_tree. Creation and deletion are also supported but restricted to a small subset of allowed users and organizations on the Hub.

>>> from huggingface_hub import kernel_info
>>> kernel_info("kernels-community/yoso")
KernelInfo(id='kernels-community/yoso', author='kernels-community', downloads=0, gated=False, last_modified=datetime.datetime(2026, 4, 3, 22, 27, 25, tzinfo=datetime.timezone.utc), likes=0, private=False)

📚 Documentation: Repository guide

📖 Documentation

🐛 Bug and typo fixes

🏗️ Internal

v1.9.0

↗
[v1.9.0] Agent-Aware CLI, Spaces Volumes, and more

🚀 Spaces Volumes: Mount Models, Datasets, and Buckets Directly

Hugging Face Spaces now support mounting volumes, giving your Space direct filesystem access to models, datasets, and storage buckets. This replaces the deprecated persistent storage feature.

from huggingface_hub import HfApi, Volume

api = HfApi()
api.set_space_volumes(
    repo_id="username/my-space",
    volumes=[
        Volume(type="model", source="username/my-model", mount_path="/models", read_only=True),
        Volume(type="bucket", source="username/my-bucket", mount_path="/data"),
    ],
)

Volumes can also be set at creation time via create_repo(space_volumes=...) and duplicate_repo(space_volumes=...), and from the CLI with the --volume / -v flag:

# Create a Space with volumes mounted
hf repos create my-space --type space --space-sdk gradio \
    -v hf://gpt2:/models -v hf://buckets/org/b:/data

# Duplicate a Space with volumes
hf repos duplicate org/my-space my-space --type space \
    -v hf://gpt2:/models -v hf://buckets/org/b:/data
  • Add support for mounted volumes by @Wauplin in #4018
  • Support volumes at repo creation and duplication by @Wauplin in #4035

🤖 The hf CLI Now Auto-Detects AI Agents and Adapts Its Output

AI coding agents (Claude Code, Cursor, Codex, Copilot, Gemini, ...) increasingly use the hf CLI to interact with the Hub. Until now, the output was designed for humans - ANSI colors, padded tables, emoji booleans, truncated cells - making it hard for agents to parse reliably.

Starting with v1.9, the CLI automatically detects when it's running inside an agent and adapts its output: no ANSI, no truncation, tab-separated tables, compact JSON, full timestamps. No configuration needed - it just works. This is only a first step toward making the hf CLI the primary entry point to the Hugging Face Hub for AI agents!

Agent mode is auto-detected but you can also force a mode explicitly with --format:

hf models ls --limit 5                  # auto-detect
hf models ls --limit 5 --format agent   # force agent-friendly output
hf models ls --limit 5 --format json    # structured JSON
hf models ls --limit 5 --format quiet   # IDs only, great for piping

Here's what an agent sees compared to a human:

hf auth whoami

# Human
✓ Logged in
  user: Wauplin
  orgs: huggingface, awesome-org

# Agent
user=Wauplin orgs=huggingface,awesome-org

# JSON
{"user": "Wauplin", "orgs": ["huggingface", "awesome-org"]}

hf models ls --author google --limit 3

# Human
ID                         DOWNLOADS TRENDING_SCORE
-------------------------- --------- --------------
google/embeddinggemma-300m 1213145   17            
google/gemma-3-4b-it       1512637   16            
google/gemma-3-27b-it      988618    12   

# Agent (TSV, no truncation, no ANSI)
id      downloads       trending_score
google/embeddinggemma-300m      1213145 17
google/gemma-3-4b-it    1512637 16
google/gemma-3-27b-it   988618  12

hf models info google/gemma-3-27b-it

# Human — pretty-printed JSON (indent=2)
{
  "id": "google/gemma-3-27b-it",
  "author": "google",
  ...
}

# Agent — compact JSON (~40% fewer tokens)
{"id": "google/gemma-3-27b-it", "author": "google", "card_data": ...}

Commands migrated so far: hf models ls|info, hf datasets ls|info|parquet|sql, hf spaces ls|info, hf papers ls|search|info, hf auth whoami. More commands will be migrated soon

  • Add out output singleton with agent/human mode rendering by @hanouticelina in #4005
  • Migrate models, datasets, spaces, papers to out singleton by @hanouticelina in #4026
  • Add FormatWithAutoOpt with callback to auto-set output mode by @hanouticelina in #4028
  • Add tests for out output singleton by @hanouticelina in #4020
  • Add agent detection helpers by @hanouticelina in #4015
  • Enrich CLI errors with available options and commands by @hanouticelina in #4034

🧩 Install Agent Skills from the Hugging Face Marketplace

The hf skills add command now supports installing skills directly from the Hugging Face skills marketplace (https://github.com/huggingface/skills) - pre-built tools that give AI agents new capabilities.

# Install a marketplace skill
hf skills add gradio

# Install with Claude Code integration
hf skills add huggingface-gradio --claude

# Upgrade all installed skills
hf skills upgrade
  • Support skills from hf skills by @burtenshaw in #3956
  • Improve hf CLI skill description for better agent triggering by @hanouticelina in #3973

🔧 More CLI Improvements

  • Auto-install official HF CLI extensions on first invocation by @hanouticelina in #4007
  • Add summary field to hf papers search CLI output by @Wauplin in #4006
  • Interactive CLI autoupdate prompt by @Wauplin in #3983

🔧 Other Improvements

  • Clarify 404 access guidance in errors by @Pierrci in #4010
  • Add HF_HUB_DISABLE_SYMLINKS env variable to force no-symlink cache by @Wauplin in #4032
  • Add CACHEDIR.TAG to cache directories by @Wauplin in #4030
  • Support None type in strict dataclass by @Wauplin in #3987
  • Reject bool/int cross-type confusion in @strict dataclass validation by @Wauplin in #3992

🐛 Bug Fixes

  • Fix PyTorchModelHubMixin not calling eval() on safetensors load by @joaquinhuigomez in #3997
  • Bump to hf-xet 1.4.3 and add regression test by @Wauplin in #4019
  • Validate shard filenames in sharded checkpoint index files by @Wauplin in #4033
  • Fix test_create_commit_conflict test by @Wauplin in #3986
  • Do not scan CACHEDIR.TAG file in cache by @Wauplin in #4036
  • Deduplicate repo folder name generation logic by @cphlipot in #4024

📖 Documentation

  • Add tip about AI agents skill to CLI guide by @gary149 in #3970
  • Link to Hub local cache docs from manage-cache guide by @Wauplin in #3989
  • Note that environment variables are read at import time by @Wauplin in #3990
  • Add DatasetLeaderboardEntry and EvalResultEntry to docs reference by @pcuenca in #3982
  • Fix typos and outdated references in CONTRIBUTING.md by @GopalGB in #4009
  • no explicit models/ in hf:// protocol by @lhoestq in #3980
  • Add CLAUDE.md symlink pointing to AGENTS.md by @hanouticelina in #4013

🏗️ Internal

v1.8.0

↗
[v1.8.0] Mounted volumes on Jobs, complete papers CLI, and more

🚀 Jobs can now mount volumes

Jobs can now access Hugging Face repositories (models, datasets, Spaces) and Storage Buckets directly as mounted volumes in their containers. This enables powerful workflows like running queries directly against datasets, loading models without explicit downloads, and persisting training checkpoints to buckets.

from huggingface_hub import run_job, Volume

job = run_job(
    image="duckdb/duckdb",
    command=["duckdb", "-c", "SELECT * FROM '/data/**/*.parquet' LIMIT 5"],
    volumes=[
        Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data"),
    ],
)
hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/data duckdb/duckdb duckdb -c "SELECT * FROM '/data/**/*.parquet' LIMIT 5"
  • Add volume mounting support for buckets and repos by @XciD in #3936

📖 Papers CLI is now complete

The hf papers command now has full functionality: search papers by keyword, get structured JSON metadata, and read the full paper content as markdown. The ls command is also enhanced with new filters for week, month, and submitter.

# Search papers
hf papers search "vision language"

# Get metadata
hf papers info 2601.15621

# Read as markdown
hf papers read 2601.15621
  • Complete hf papers with search, info, read + ls filters by @mishig25 in #3952

🖥️ CLI repo ID shorthand

You can now use repo ID prefixes like spaces/user/repo, datasets/user/repo, and models/user/repo as a shorthand for user/repo --type space. This works automatically for all CLI commands that accept a --type flag.

# Before
hf download user/my-space --type space
hf discussions list user/my-dataset --type dataset

# After
hf download spaces/user/my-space
hf discussions list datasets/user/my-dataset
  • Accept spaces/user/repo as repo ID prefix shorthand by @Wauplin in #3929

🔧 More repo visibility options

Repositories can now be created or updated with explicit visibility settings (--public, --protected) alongside the existing --private flag. This adds a visibility parameter to HfApi.create_repo, update_repo_settings, and duplicate_repo, with --protected available for Spaces only.

Protected Spaces allow for private code while being publicly accessible.

  • Add visibility parameter to HfApi repo create/update/duplicate methods by @hanouticelina in #3951

🖥️ CLI

  • Add space-specific options to hf repos create and hf repos duplicate by @Wauplin in #3888
  • Add --format json to hf auth whoami by @hanouticelina in #3938 — docs
  • Expand nested groups, inline flags & common options glossary in SKILL.md by @hanouticelina in #3941
  • Include common options inline in generated SKILL.md by @hanouticelina in #3955
  • Fix hf extensions install on uv-managed Python by using uv when available by @hanouticelina in #3957
  • Add dataset leaderboard method to HfApi by @davanstrien in #3953
  • More explicit spaces hot-reload docs by @cbensimon in #3964
  • Update hardware flavors with HF Hub (cpu-performance, sprx8, h200, inf2x6) by @cbensimon in #3965 — docs

🔧 Other QoL Improvements

  • Rename .env to .venv in virtual environment instructions by @julien-c in #3939 — docs
  • Fix typo in --every help text by @julien-c in #3950
  • More robust stream to stdout in hf cp command by @Wauplin in #3968

🐛 Bug and typo fixes

  • Use module logger consistently and narrow bare except clauses by @mango766 in #3924
  • Fix HfFileSystem glob in missing subdir by @lhoestq in #3935

🏗️ Internal

  • Remove conda workflow by @Wauplin in #3928
  • Replace huggingface-cli with hf in brew upgrade command by @hanouticelina in #3946
  • Fix version check message leaking into generated SKILL.md by @hanouticelina in #3949
  • Mention hf-mount in CLI skill by @hanouticelina in #3966
  • Use huggingface-hub-bot for post-release PR creation in release.yml by @Wauplin in #3967

v1.7.2

↗
[1.7.2] `hf` CLI skill improvements, `uv` extension installs & bug fixes

🛠️ CLI improvements

hf CLI skill now fully expands subcommand groups and inlines all flags and options, making the CLI self-describing and easier for agents to discover.

  • Expand nested groups, inline flags & common options glossary in SKILL.md (#3941) by @hanouticelina
  • include common options inline (#3955) by @hanouticelina

hf extension install now uses uv for Python extension installation when available making extension installation faster:


> hyperfine "hf extensions install alvarobartt/hf-mem --force"
# Before
Benchmark 1: hf extensions install alvarobartt/hf-mem --force
  Time (mean ± σ):      3.490 s ±  0.220 s    [User: 1.925 s, System: 0.445 s]
  Range (min … max):    3.348 s …  4.097 s    10 runs

# After
Benchmark 1: hf extensions install alvarobartt/hf-mem --force
  Time (mean ± σ):     519.6 ms ± 119.7 ms    [User: 216.6 ms, System: 95.2 ms]
  Range (min … max):   371.6 ms … 655.2 ms    10 runs
  • Use uv python extension installation when available (#3957) by @hanouticelina

Other QoL improvements:

  • Add --format json to hf auth whoami (#3938) by @hanouticelina
  • Replace huggingface-cli with hf in brew upgrade command (#3946) by @hanouticelina

🐛 Bug & Typo fixes

  • Fix HfFileSystem glob in missing subdirectory (#3935) by @lhoestq
  • Fix: use module logger consistently and narrow bare except clauses (#3924) by @mango766
  • Fix typo in --every help text (#3950) by @julien-c

📚 Docs

  • Rename .env to .venv in virtual environment instructions (#3939) by @julien-c

🏗️ Internal

  • Remove conda workflow (#3928) by @Wauplin
  • Fix version check message leaking into generated SKILL.md (#3949) by @hanouticelina

Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v1.7.1...v1.7.2

v1.7.0

↗
[v1.7.0] pip-installable CLI extensions and multiple QoL improvements

This release brings major improvements to the hf CLI with extension discoverability, unified list commands, and multiple QoL improvements in the CLI.

🎉 The Homebrew formula of the Hugging Face CLI has been renamed to hf. Existing users just need to run brew update - Homebrew handles the rename automatically. New users can install with brew install hf.

🧩 CLI Extensions: pip-installable packages and discoverability

The hf CLI extensions system gets a major upgrade in this release. Extensions can now be full Python packages (with a pyproject.toml) installed in isolated virtual environments, in addition to the existing shell script approach. This means extension authors can use Python dependencies without conflicting with the user's system. The install command auto-detects whether a GitHub repo is a script or a Python package and handles both transparently.

A new hf extensions search command lets users discover available extensions directly from the terminal by querying GitHub repositories tagged with the hf-extension topic. Results are sorted by stars and show whether each extension is already installed locally. Additionally, a comprehensive guide on how to build, publish, and make extensions discoverable has been added to the documentation.

# Install a Python-based extension
hf extensions install alvarobartt/hf-mem

# Discover available extensions
hf extensions search
NAME   REPO                    STARS DESCRIPTION                         INSTALLED
------ ----------------------- ----- ----------------------------------- ---------
claude hanouticelina/hf-claude     2 Extension for `hf` CLI to launch... yes
agents hanouticelina/hf-agents       HF extension to run local coding...
  • [CLI] Add pip installable repos support to hf extensions by @Wauplin in #3892
  • [CLI] Add hf extensions search command by @julien-c in #3905
  • [Docs] How to build a CLI extension guide by @Wauplin in #3908

📚 Documentation: Create a CLI extension

🔐 hf auth login CLI update

A new --force flag lets you explicitly go through the full login flow again when needed, for example to switch tokens.

# Already logged in — returns immediately
hf auth login

# Force re-login to switch tokens
hf auth login --force
  • Default to skipping login if already logged in and add --force flag by @hanouticelina in #3920

📚 Documentation: CLI guide

📦 Xet optimizations and fixes

hf-xet has been bumped to v1.4.2 with some optimizations:

  • Avoid duplicate sha256 computation when uploading to a model/dataset repo
  • Skip sha256 computation when uploading to a bucket This should greatly improve upload speed of large files.

The hf-xet bump also comes with a fix for deadlocks / stall on large file downloads.

See hf-xet release notes for more details.

  • feat: pass pre-computed SHA-256 to hf_xet upload by @XciD in #3876
  • feat: pass skip_sha256=True to hf_xet for bucket uploads by @Wauplin in #3900

🖥️ CLI QoL Improvements

  • Add num_parameters filtering to hf API and CLI by @evalstate in #3897 — docs
  • [CLI] Normalize all list/ls commands to use list | ls alias by @julien-c in #3901
  • [CLI] Add --format and --quiet options to hf papers ls by @julien-c in #3903
  • [CLI] Add hidden --json shorthand for --format json by @Wauplin in #3919
  • Allow 'hf skills add' default directory by @Wauplin in #3923

🔧 Other QoL Improvements

  • Add used_storage field to ModelInfo, DatasetInfo, and SpaceInfo by @julien-c in #3911
  • Make sure all expand attributes are official ModelInfo/DatasetInfo/SpaceInfo by @Wauplin in #3918

📖 Documentation

  • [Docs] Update some community CLI examples by @Wauplin in #3899
  • [Docs] Update Homebrew install command to hf by @julien-c in #3902

🐛 Bug and typo fixes

  • snapshot_download operation raises the generic exception even when actual error is different. by @pavankumarch470 in #3914

🏗️ Internal

  • [Internal] Don't trigger Skills sync workflow on release candidate by @hanouticelina in #3893
  • [Internal] Fix skills path in Skills sync workflow by @hanouticelina in #3894
  • [CI] All-in-one Github Action for releases by @Wauplin in #3916

v1.6.0

↗
[v1.6.0] New CLI commands, Bucket fsspec support, and more

This release brings significant new CLI commands for managing Spaces, Datasets, Discussions, and Webhooks, along with HfFileSystem support for Buckets and a CLI extension system.

🚀 New CLI commands

We've added several new CLI command groups to make interacting with the Hub even easier from your terminal.

New hf spaces dev-mode command

You can now enable or disable dev mode on Spaces directly from the CLI. When enabling dev mode, the command waits for the Space to be ready and prints connection instructions (web VSCode, SSH, local VSCode/Cursor). This makes iterating on Spaces much faster by allowing you to restart your application without stopping the Space container.

# Enable dev mode
hf spaces dev-mode username/my-space

# Disable dev mode
hf spaces dev-mode username/my-space --stop
  • Add hf spaces dev-mode command by @lhoestq in #3824
New hf discussions command group

You can now manage discussions and pull requests on the Hub directly from the CLI. This includes listing, viewing, creating, commenting on, closing, reopening, renaming, and merging discussions and PRs.

# List open discussions and PRs on a repo
hf discussions list username/my-model

# Create a new discussion
hf discussions create username/my-model --title "Feature request" --body "Description"

# Create a pull request
hf discussions create username/my-model --title "Fix bug" --pull-request

# Merge a pull request
hf discussions merge username/my-model 5 --yes
  • Add hf discussions command group by @Wauplin in #3855
  • Rename hf discussions view to hf discussions info by @Wauplin in #3878
New hf webhooks command group

Full CLI support for managing Hub webhooks is now available. You can list, inspect, create, update, enable/disable, and delete webhooks directly from the terminal.

# List all webhooks
hf webhooks ls

# Create a webhook
hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased

# Enable / disable a webhook
hf webhooks enable webhook_id
hf webhooks disable webhook_id

# Delete a webhook
hf webhooks delete webhook_id
  • Add hf webhooks CLI commands by @omkar-334 in #3866
New hf datasets parquet and hf datasets sql commands

Two new commands make it easy to work with dataset parquet files. Use hf datasets parquet to discover parquet file URLs, then query them with hf datasets sql using DuckDB.

# List parquet URLs for a dataset
hf datasets parquet cfahlgren1/hub-stats
hf datasets parquet cfahlgren1/hub-stats --subset models --split train

# Run SQL queries on dataset parquet
hf datasets sql "SELECT COUNT(*) FROM read_parquet('https://huggingface.co/api/datasets/...')"
  • Add hf datasets parquet and hf datasets sql commands by @cfahlgren1 in #3833
New hf repos duplicate command

You can now duplicate any repository (model, dataset, or Space) using a unified command. This replaces the previous duplicate_space method with a more general solution.

# Duplicate a Space
hf repos duplicate multimodalart/dreambooth-training --type space

# Duplicate a dataset
hf repos duplicate openai/gdpval --type dataset
  • Add duplicate_repo method and hf repos duplicate command by @Wauplin in #3880

🪣 Bucket support in HfFileSystem

The HfFileSystem now supports buckets, providing S3-like object storage on Hugging Face. You can list, glob, download, stream, and upload files in buckets using the familiar fsspec interface.

from huggingface_hub import hffs

# List files in a bucket
hffs.ls("buckets/my-username/my-bucket/data")

# Read a remote file
with hffs.open("buckets/my-username/my-bucket/data/file.txt", "r") as f:
    content = f.read()

# Read file content as string
hffs.read_text("buckets/my-username/my-bucket/data/file.txt")
  • Add bucket API support in HfFileSystem by @lhoestq in #3807
  • Add docs on hf://buckets by @lhoestq in #3875
  • Remove bucket warning in docs by @Wauplin in #3854

📦 Extensions now support pip install

The hf extensions system now supports installing extensions as Python packages in addition to standalone executables. This makes it easier to distribute and install CLI extensions.

# Install an extension
> hf extensions install hanouticelina/hf-claude
> hf extensions install alvarobartt/hf-mem

# List them
> hf extensions list
COMMAND   SOURCE                  TYPE   INSTALLED  DESCRIPTION                        
--------- ----------------------- ------ ---------- -----------------------------------
hf claude hanouticelina/hf-claude binary 2026-03-06 Launch Claude Code with Hugging ...
hf mem    alvarobartt/hf-mem      python 2026-03-06 A CLI to estimate inference memo...

# Run extension
> hf claude --help
Usage: claude [options] [command] [prompt]

Claude Code - starts an interactive session by default, use -p/--print for non-interactive output
  • Add pip installable repos support to hf extensions by @Wauplin in #3892
Show installed extensions in hf --help

The CLI now shows installed extensions under an "Extension commands" section in the help output.

Other QoL improvements

  • Add NVIDIA provider support to InferenceClient by @manojkilaru97 in #3886
  • Bump hf_xet minimal package version to >=1.3.2 for better throughput by @Wauplin in #3873
  • Fix CLI errors formatting to include repo_id, repo_type, bucket_id by @Wauplin in #3889

📚 Documentation updates

  • Fixed sub-headings for hf cache commands in the doc by @mostafatouny in #3877

🐛 Bug and typo fixes

  • Fix: quote uv args in bash -c to prevent shell redirection by @XciD in #3857
  • Fix typo in generated Skill by @hanouticelina in #3890
  • Fix ty diagnostics in upload, filesystem, and repocard helpers by @hanouticelina in #3891

💔 Breaking changes

  • Remove deprecated direction argument in list_models/datasets/spaces by @Wauplin in #3882

🏗️ Internal

  • Release note skill attempt by @Wauplin in #3853
  • Prepare for v1.6 by @Wauplin in #3860
  • Skip git clone test by @Wauplin in #3881
  • Add Sync hf CLI Skill workflow by @hanouticelina in #3885
  • [Release notes] doc diffs, better skill, concurrent fetching by @Wauplin in #3887
  • Propagate filtered headers to xet by @bpronan in #3858

v1.5.0

↗
[v1.5.0]: Buckets API, Agent-first CLI, Spaces Hot-Reload and more

This release introduces major new features including Buckets (xet-based large scale object storage), CLI Extensions, Space Hot-Reload, and significant improvements for AI coding agents. The CLI has been completely overhauled with centralized error handling, better help output, and new commands for collections, papers, and more.

🪣 Buckets: S3-like Object Storage on the Hub

Buckets provide S3-like object storage on Hugging Face, powered by the Xet storage backend. Unlike repositories (which are git-based and track file history), buckets are remote object storage containers designed for large-scale files with content-addressable deduplication. Use them for training checkpoints, logs, intermediate artifacts, or any large collection of files that doesn't need version control.

# Create a bucket
hf buckets create my-bucket --private

# Upload a directory
hf buckets sync ./data hf://buckets/username/my-bucket

# Download from bucket
hf buckets sync hf://buckets/username/my-bucket ./data

# List files
hf buckets list username/my-bucket -R --tree

The Buckets API includes full CLI and Python support for creating, listing, moving, and deleting buckets; uploading, downloading, and syncing files; and managing bucket contents with include/exclude patterns.

  • Buckets API and CLI by @Wauplin in #3673
  • Support bucket rename/move in API + CLI by @Wauplin in #3843
  • Add 'sync_bucket' to HfApi by @Wauplin in #3845
  • hf buckets file deletion by @Wauplin in #3849
  • Update message when no buckets found by @Wauplin in #3850
  • Buckets doc hf install by @julien-c in #3846

📚 Documentation: Buckets guide

🤖 AI Agent Support

This release includes several features designed to improve the experience for AI coding agents (Claude Code, OpenCode, Cursor, etc.):

  • Centralized CLI error handling: Clean user-facing messages without tracebacks (set HF_DEBUG=1 for full traces) by @hanouticelina in #3754
  • Token-efficient skill: The hf skills add command now installs a compact skill (~1.2k tokens vs ~12k before) by @hanouticelina in #3802
  • Agent-friendly hf jobs logs: Prints available logs and exits by default; use -f to stream by @davanstrien in #3783
  • Add AGENTS.md: Dev setup and codebase guide for AI agents by @Wauplin in #3789
# Install the hf-cli skill for Claude
hf skills add --claude

# Install for project-level
hf skills add --project
  • Add hf skills add CLI command by @julien-c in #3741
  • hf skills add installs to central location with symlinks by @hanouticelina in #3755
  • Add Cursor skills support by @NielsRogge in #3810

🔥 Space Hot-Reload (Experimental)

Hot-reload Python files in a Space without a full rebuild and restart. This is useful for rapid iteration on Gradio apps.

# Open an interactive editor to modify a remote file
hf spaces hot-reload username/repo-name app.py

# Take local version and patch remote
hf spaces hot-reload username/repo-name -f app.py
  • feat(spaces): hot-reload by @cbensimon in #3776
  • fix hot reload reference part.2 by @cbensimon in #3820

🖥️ CLI Improvements

New Commands
  • Add hf papers ls to list daily papers on the Hub by @julien-c in #3723
  • Add hf collections commands (ls, info, create, update, delete, add-item, update-item, delete-item) by @Wauplin in #3767
CLI Extensions

Introduce an extension mechanism to the hf CLI. Extensions are standalone executables hosted in GitHub repositories that users can install, run, and remove with simple commands. Inspired by gh extension.

# Install an extension (defaults to huggingface org)
hf extensions install hf-claude

# Install from any GitHub owner
hf extensions install hanouticelina/hf-claude

# Run an extension
hf claude

# List installed extensions
hf extensions list
Output Format Options
  • Add --format {table,json} and -q/--quiet to hf models ls, hf datasets ls, hf spaces ls, hf endpoints ls by @hanouticelina in #3735
  • Align hf jobs ps output with standard CLI pattern by @davanstrien in #3799
  • Dynamic table columns based on --expand field by @hanouticelina in #3760
Usability
  • Improve hf CLI help output with examples and documentation links by @hanouticelina in #3743
  • Add -h as short alias for --help by @assafvayner in #3800
  • Add hidden --version flag by @Wauplin in #3784
  • Add --type as alias for --repo-type by @Wauplin in #3835
  • Better handling of aliases in documentation by @Wauplin in #3840
  • Print first example only in group command --help by @Wauplin in #3841
  • Subfolder download: hf download repo_id subfolder/ now works as expected by @Wauplin in #3822
Jobs CLI

List available hardware:

✗ hf jobs hardware
NAME            PRETTY NAME            CPU      RAM     ACCELERATOR       COST/MIN COST/HOUR 
--------------- ---------------------- -------- ------- ----------------- -------- --------- 
cpu-basic       CPU Basic              2 vCPU   16 GB   N/A               $0.0002  $0.01     
cpu-upgrade     CPU Upgrade            8 vCPU   32 GB   N/A               $0.0005  $0.03     
cpu-performance CPU Performance        32 vCPU  256 GB  N/A               $0.3117  $18.70    
cpu-xl          CPU XL                 16 vCPU  124 GB  N/A               $0.0167  $1.00     
t4-small        Nvidia T4 - small      4 vCPU   15 GB   1x T4 (16 GB)     $0.0067  $0.40     
t4-medium       Nvidia T4 - medium     8 vCPU   30 GB   1x T4 (16 GB)     $0.0100  $0.60     
a10g-small      Nvidia A10G - small    4 vCPU   15 GB   1x A10G (24 GB)   $0.0167  $1.00  
...

Also added a ton of fixes and small QoL improvements.

  • Support multi GPU training commands (torchrun, accelerate launch) by @lhoestq in #3674
  • Pass local script and config files to job by @lhoestq in #3724
  • List available hardware with hf jobs hardware by @Wauplin in #3693
  • Better jobs filtering in CLI: labels and negation (!=) by @lhoestq in #3742
  • Accept namespace/job_id format in jobs CLI commands by @davanstrien in #3811
  • Pass namespace parameter to fetch job logs by @Praful932 in #3736
  • Add more error handling output to hf jobs cli commands by @davanstrien in #3744
  • Fix hf jobs commands crashing without a TTY by @davanstrien in #3782

🤖 Inference

  • Add dimensions & encoding_format parameter to InferenceClient for output embedding size by @mishig25 in #3671
  • feat: zai-org provider supports text to image by @tomsun28 in #3675
  • Fix fal image urls payload by @hanouticelina in #3746
  • Fix Replicate image-to-image compatibility with different model schemas by @hanouticelina in #3749
  • Accelerator parameter support for inference endpoints by @Wauplin in #3817

🔧 Other QoL Improvements

  • Support setting Label in Jobs API by @Wauplin in #3719
  • Document built-in environment variables in Jobs docs (JOB_ID, ACCELERATOR, CPU_CORES, MEMORY) by @Wauplin in #3834
  • Fix ReadTimeout crash in no-follow job logs by @davanstrien in #3793
  • Add evaluation results module (EvalResultEntry, parse_eval_result_entries) by @hanouticelina in #3633
  • Add source org field to EvalResultEntry by @hanouticelina in #3694
  • Add limit param to list_papers API method by @Wauplin in #3697
  • Add num_papers field to Organization class by @cfahlgren1 in #3695
  • Update MAX_FILE_SIZE_GB from 50 to 200 by @davanstrien in #3696
  • List datasets benchmark alias (benchmark=True → benchmark="official") by @Wauplin in #3734
  • Add notes field to EvalResultEntry by @Wauplin in #3738
  • Make task_id required in EvalResultEntry by @Wauplin in #3718
  • Repo commit count warning for upload_large_folder by @Wauplin in #3698
  • Replace deprecated is_enterprise boolean by plan string in org info by @Wauplin in #3753
  • Update hardware list in SpaceHardware enum by @lhoestq in #3756
  • Use HF_HUB_DOWNLOAD_TIMEOUT as default httpx timeout by @Wauplin in #3751
  • No timeout by default when using httpx by @Wauplin in #3790
  • Log 'x-amz-cf-id' on http error (if no request id) by @Wauplin in #3759
  • Parse xet hash from tree listing by @seanses in #3780
  • Require filelock>=3.10.0 for mode= parameter support by @Wauplin in #3785
  • Add overload decorators to HfApi.snapshot_download for dry_run typing by @Wauplin in #3788
  • Dataclass doesn't call original __init__ by @zucchini-nlp in #3818
  • Strict dataclass sequence validation by @Wauplin in #3819
  • Check if dataclass.repr=True before wrapping by @zucchini-nlp in #3823

💔 Breaking Changes

  • hf jobs ps removes old Go-template --format '{{.id}}' syntax. Use -q for IDs or --format json | jq for custom extraction by @davanstrien in #3799
  • Migrate to hf repos instead of hf repo (old command still works but shows deprecation warning) by @Wauplin in #3848
  • Migrate hf repo-files delete to hf repo delete-files (old command hidden from help, shows deprecation warning) by @Wauplin in #3821

🐛 Bug and typo fixes

  • Fix severe performance regression in streaming by keeping a byte iterator in HfFileSystemStreamFile by @leq6c in #3685
  • Fix endpoint not forwarded in CommitUrl by @Wauplin in #3679
  • Fix HfFileSystem.resolve_path() with special char @ by @lhoestq in #3704
  • Fix cache verify incorrectly reporting folders as missing files by @Mitix-EPI in #3707
  • Fix multi user cache lock permissions by @hanouticelina in #3714
  • Default _endpoint to None in CommitInfo, fixes tiny regression from v1.3.3 by @tomaarsen in #3737
  • Filter datasets by benchmark:official by @Wauplin in #3761
  • Fix file corruption when server ignores Range header on download retry by @XciD in #3778
  • Fix Xet token invalid on repo recreation by @Wauplin in #3847
  • Correct typo 'occured' to 'occurred' by @thecaptain789 in #3787
  • Fix typo in CLI error handling by @hanouticelina in #3757

📖 Documentation

  • Add link to Hub Jobs documentation by @gary149 in #3712
  • Update HTTP backend configuration link to main branch by @IliasAarab in #3713
  • Update CLI help output in docs to include new commands by @julien-c in #3722
  • Wildcard pattern documentation by @hanouticelina in #3710
  • Deprecate hf_transfer references in Korean and German translations by @davanstrien in #3804
  • Use SPDX license identifier 'Apache-2.0' by @yesudeep in #3814
  • Correct img tag style in README.md by @sadnesslovefreedom-debug in #3689

🏗️ Internal

  • Change external dependency from typer-slim to typer by @svlandeg in #3797
  • Remove shellingham from the required dependencies by @hanouticelina in #3798
  • Ignore unused-ignore-comment warnings in ty for mypy compatibility by @hanouticelina in #3691
  • Remove new unused-type-ignore-comment warning from ty by @hanouticelina in #3803
  • Fix curlify when debug logging is enabled for streaming requests by @hanouticelina in #3692
  • Remove canonical dataset test case by @hanouticelina in #3740
  • Remove broad exception handling from CLI job commands by @hanouticelina in #3748
  • CI windows permission error by @Wauplin in #3700
  • Upgrade GitHub Actions to latest versions by @salmanmkc in #3729
  • Stabilize lockfile test in file_download tests by @hanouticelina in #3815
  • Fix ty invalid assignment in CollectionItem by @hanouticelina in #3831
  • Use inference_provider instead of inference in tests by @hanouticelina in #3826
  • Fix tqdm windows test failure by @Wauplin in #3844
  • Add test for check if dataclass.repr=True before wrapping by @Wauplin in #3852
  • Prepare for v1.5 by @Wauplin in #3781
Sources
1
Category
AI
Tags
pythonsdk
.json·.md·.atom