●Change8

v1.22.0

Breaking Changes
📦 huggingface-hubView on GitHub →
⚠ 2 breaking✨ 11 features🐛 6 fixes⚡ 1 deprecations🔧 24 symbols

Summary

This release introduces Sandboxes, isolated cloud machines accessible via API and CLI, and significantly speeds up snapshot downloads by caching repository tree listings. The underlying CLI framework was also migrated from Typer to Click.

⚠️ Breaking Changes

  • The `upload_large_folder` function and `hf upload-large-folder` CLI command are deprecated in favor of `upload_folder` / `hf upload`, which now handle large and resumable uploads.
  • `allow_patterns`/`ignore_patterns` matching in repository object filtering is now case-sensitive on all platforms. On Windows, patterns like `*.PDF` will no longer match `file.pdf`.

Migration Steps

  1. If you relied on case-insensitive pattern matching for filtering repository objects on Windows (e.g., using `*.PDF`), update your patterns to match the exact case of the filenames.
  2. Replace usage of `upload_large_folder` or `hf upload-large-folder` with `upload_folder` or `hf upload` respectively.

✨ New Features

  • Introduction of Sandboxes: isolated cloud machines built on Jobs, accessible via `Sandbox.create`, `SandboxPool`, and the `hf sandbox` CLI, supporting live-streamed output and file transfer.
  • Sandboxes support background processes via `sbx.run(..., background=True)` or `hf sandbox spawn`.
  • Added port proxy functionality (`Sandbox.proxy_url_for`) to reach servers running inside a sandbox from the outside.
  • `snapshot_download` now caches repository file listings under a new `trees/` folder for faster subsequent downloads of the same commit.
  • The `hf` CLI has been rebuilt using Click 8.x instead of Typer, improving custom help rendering and error enrichment.
  • Added `hf discussions edit` command to the CLI.
  • CLI command `hf cache ls` now flags leftover `.incomplete` files, and `hf cache prune` removes them automatically.
  • Added support for automatic speech recognition via the deepinfra inference provider.
  • Jobs now support syncing local directories to a `jobs-artifacts` bucket and mounting them using the `sync_job_volume` helper and the `-v` flag in `hf jobs run`/`uv run`.
  • Added `hf jobs scheduled trigger ...` command to manually trigger scheduled jobs.
  • HTTP client now honors the standard `Retry-After` header in `http_backoff`.

🐛 Bug Fixes

  • Fixed escaped backslash handling when parsing .env values in the CLI.
  • Percent-encoded the revision in HfUri.to_url.
  • Fixed `parse_size` to accept two-letter byte units (KB/MB/GB/TB/PB) for size thresholds in CLI filters.
  • Fixed KeyError in `get_dataset_leaderboard` when an entry lacks a source.
  • Stopped suggesting reporting errors when a Colab vault error occurs.
  • Ensured `huggingface_hub.templates` are included in wheels by fixing `find_namespace_packages` configuration.

Affected Symbols

SandboxSandbox.createSandboxPoolSandbox.runhf sandboxSandbox.proxy_url_forsnapshot_downloadhf_hub_downloadIncompleteSnapshotErrortyper_factoryupload_large_folderupload_folderhf upload-large-folderhf uploadfilter_repo_objectsallow_patternsignore_patternsget_dataset_leaderboardhf cache lshf cache prunehf discussions edithttp_backoffhf jobs runhf jobs scheduled trigger

⚡ Deprecations

  • `upload_large_folder` API and `hf upload-large-folder` CLI are deprecated; use `upload_folder` and `hf upload` instead.