●Change8

v1.20.0

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

Summary

This release introduces browser-based OAuth login as the default authentication method and significantly overhauls folder uploads for speed and reliability using a streamed, multi-commit pipeline. Additionally, Hugging Face Jobs now supports waiting for completion, SSH access, and custom container deployments for Inference Endpoints.

⚠️ 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 use the new `hf jobs wait` command.
  • 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 opened).

Migration Steps

  1. If relying on the exit code of non-detached `hf jobs run` or `hf jobs uv run`, update scripts to check the job status explicitly instead of assuming exit code 0 on completion.
  2. If using `hf upload` on large folders and expecting a PR only if changes exist, be aware that passing `create_pr=True` will now always open a PR against main if the upload runs.

✨ New Features

  • Introduced browser-based OAuth Device Code flow as the default for `hf auth login` and `login()` in Python, replacing direct token pasting.
  • OAuth tokens now include refresh tokens, allowing `get_token()` to transparently refresh tokens expiring within 24 hours.
  • Added support for streaming structured events during `hf auth login` when run by an AI agent.
  • `hf auth list` now displays the expiry date for stored tokens.
  • `notebook_login()` now uses `IPython.display.HTML` directly, removing the `ipywidgets` dependency.
  • Revamped `hf upload` and `upload_folder` using a streamed, multi-commit pipeline via `XetSession` API for faster and more reliable uploads of large folders.
  • New resumable and stateless upload behavior for large folders; re-running an interrupted upload skips already committed files.
  • Large folders are automatically split into adaptive commits (64-1024 files) based on commit duration.
  • Added live progress bar tracking preparing, uploading, and committing stages for large folder uploads.
  • Added `HfApi.wait_for_job()` and `hf jobs wait` to block until one or more Jobs reach a terminal stage.
  • Added SSH access to running Jobs via `hf jobs ssh <job_id>`, which now waits for the Job to reach `RUNNING` state.
  • Added support for deploying custom Docker containers via `hf endpoints deploy` using new flags like `--custom-image`, `--health-route`, `--port`, etc.

🐛 Bug Fixes

  • Replaced raw `httpx` tracebacks with cleaner, actionable messages using `hf_raise_for_status` and introduced `JobNotFoundError`.
  • Removed per-command `try/except` blocks in favor of global CLI error handling.

Affected Symbols

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

⚡ Deprecations

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