huggingface-hub 1.13.0

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

on Python PyPI

🖥️ 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