●Change8

v1.20.0.rc0

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

Summary

This release introduces browser-based OAuth login as the default authentication method and significantly overhauls large folder uploads using a streamed, multi-commit pipeline powered by Xet. Additionally, Hugging Face Jobs now support waiting for completion, SSH access, and cleaner error reporting.

⚠️ Breaking Changes

  • Non-detached `hf jobs run` / `hf jobs uv run` now exit with the Job's outcome (exit code 1 if the Job errored) instead of always exiting 0. Scripts relying on the previous behavior (always exiting 0) must be updated to check the job status or rely on the new exit code.
  • Uploading a folder via `upload_folder` or `hf upload` might result in multiple commits. If `create_pr=True` is passed, it will necessarily create a PR against main, even if some changes have been committed (previously an empty commit resulted in no PR).

Migration Steps

  1. If you rely on `hf jobs run` or `hf jobs uv run` always exiting with code 0 when running detached jobs, update scripts to check the job status explicitly or handle the new exit code (1 on error).
  2. If you use `upload_folder` with `create_pr=True`, be aware that a PR will always be created against main if any changes are uploaded.

✨ New Features

  • Introduced browser-based OAuth Device Code flow as the default for `hf auth login` and `login()`, replacing direct token pasting.
  • OAuth tokens now include refresh tokens, allowing `get_token()` to transparently refresh tokens expiring within 24 hours.
  • Added `hf auth list` to display the expiry date for stored tokens.
  • Revamped `hf upload` and `upload_folder` to use a streamed, multi-commit pipeline via `XetSession` API for faster and more reliable uploads of large folders.
  • New upload progress bar showing preparing, uploading, and committing stages for large folder uploads.
  • Added `HfApi.wait_for_job()` and `hf jobs wait` to block until Hugging Face Jobs reach a terminal stage, useful for CI scripting.
  • Implemented SSH access to running Jobs via `hf jobs ssh <job_id>`, which now waits for the job to reach the RUNNING state.
  • Jobs CLI now raises a specific `JobNotFoundError` and uses cleaner error handling instead of raw httpx tracebacks.
  • Inference Endpoints deployment via `hf endpoints deploy` now supports deploying custom Docker containers using new flags like `--custom-image`, `--health-route`, `--port`, `--command`, and `--container-args`.

🐛 Bug Fixes

  • The `notebook_login()` function now uses plain `IPython.display.HTML` instead of relying on `ipywidgets` for rendering the login link and code.
  • `hf jobs ssh` now waits for the Job to reach `RUNNING` before attempting to connect, preventing immediate failure during scheduling.

Affected Symbols

`hf auth login``login()` (Python)`get_token()``hf auth list``notebook_login()``hf upload``upload_folder``hf upload-large-folder``HfApi.wait_for_job``hf jobs wait``hf jobs run``hf jobs uv run``hf jobs ssh``JobNotFoundError``hf_raise_for_status``create_inference_endpoint`

⚡ Deprecations

  • The experimental command `hf upload-large-folder` is marked for future deprecation as its functionality is now absorbed by the revamped `hf upload`.