●Change8

Migrating to HuggingFace Hub v1.21.0.rc0

Version v1.21.0.rc0 introduces 2 breaking changes. This guide details how to update your code.

Released: 6/25/2026

2
Breaking Changes
2
Migration Steps
6
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

list_jobshf jobs pshf jobs lsfilter_repo_objects_oauth_device.pyutils._http

Breaking Changes

●Issue #1

`list_jobs()` now returns an `Iterable[JobInfo]` instead of `list[JobInfo]`. If you indexed the result (`jobs[0]`), you must now wrap the call with `list(...)` to materialize the results immediately.

●Issue #2

The CLI option `-f`/`--filter` in `hf jobs ls` is deprecated. Filtering by glob patterns, negation, or by `id`/`image`/`command` is no longer supported; use `--status` and `--label` instead.

Migration Steps

  1. 1
    If you relied on indexing the result of `list_jobs()` (e.g., `jobs[0]`), change this to `list(list_jobs())[0]` or iterate over the result.
  2. 2
    Replace usage of `-f`/`--filter` in CLI job listing commands with `--status` and `--label` arguments.

Release Summary

The Jobs listing functionality was significantly overhauled, introducing server-side filtering and lazy pagination for `list_jobs()`, and renaming the CLI command from `hf jobs ps` to `hf jobs ls`. A critical circular import bug affecting `huggingface_hub.login` was also resolved.

Need More Details?

View the full release notes and all changes for HuggingFace Hub v1.21.0.rc0.

View Full Changelog