huggingface_hub v2.2.0 Makes hf jobs stats Print One Snapshot by Default and Fixes a Race That Could Let Concurrent Downloads Skip hf_xet

Overview

huggingface_hub v2.2.0 was published on October 8, 2026 at 14:54 UTC, according to the GitHub release page. The maintainers’ notes describe it as “A small release this week, mostly bug fixes and quality-of-life improvements.” The most visible change is to the Hugging Face command-line tool: hf jobs stats now prints one snapshot and exits instead of streaming metrics until a job finishes. The release also fixes a thread race that could make concurrent downloads skip hf_xet and corrects HfFileSystem caching bugs.

What Changed

hf jobs stats returns a snapshot

Per the release notes, hf jobs stats used to stream metrics until the job finished, so “scripts and agents calling it on a running job hung until their own timeout.” It now prints the latest sample of each job once and exits, in the same way as hf jobs logs and hf spaces logs. The previous live view is available with -f/--follow. Snapshot output also accepts --format json|agent|quiet, which the notes say outputs the raw API metrics.

On the Python side, HfApi.fetch_job_metrics gets the same follow parameter as fetch_job_logs. It defaults to False and returns only the current sample, and follow=True streams until the job completes, according to the release notes. The notes list this under breaking changes: code that relied on blocking until the job completed must now pass -f/--follow or follow=True.

The author of the change, in pull request #5090 (merged October 6, 2026), wrote that the default is “one snapshot with the latest sample of each job (~1s)” and that jobs with no sample within 10s get a warning. The pull request says --follow is only allowed in human mode, because it relies on cursor-up redraws. It also explains why the flag is explicit rather than tied to terminal detection: “whether a command blocks shouldn’t depend on where it runs.”

A race in hf_xet detection

The release notes say that in a fresh process, the first concurrent hf_hub_download calls could read a placeholder version for hf_xet while another thread was still looking it up. Those calls then treated hf_xet as missing and downloaded through the plain HTTP path. According to the notes, this mostly affected parallel downloads such as snapshot_download, where some of the files skipped Xet.

Pull request #5102, merged October 7, 2026, attributes the problem to _get_version writing the placeholder "N/A" into a shared _package_versions cache before it called importlib.metadata.version. The fix resolves the version first and writes the cache once. The pull request description says concurrent first calls may still each do the lookup, but none of them can read a half-written entry. Its author reports that a new test using 8 threads fails in 10 of 10 runs on main and passes in 20 of 20 runs with the change.

HfFileSystem cache fixes

The release notes list three fixes. ls() on a newly created empty bucket returns an empty list rather than raising FileNotFoundError. Directory listings are replaced in the cache instead of appended to, which the notes say previously could produce duplicate entries from ls() after find() or ls(refresh=True). And exists(path, refresh=True) and invalidate_cache(path) now clear cached “not found” results, so a repo, branch or bucket created in the same process no longer stays missing until a full invalidate_cache().

Pull request #5106, merged October 7, 2026, adds that invalidate_cache() with no path now also clears the bucket cache, and that misses otherwise stay cached.

Other items in the notes

• A Windows fix in the CLI: the notes say quoted patterns such as --include "*.json" were expanded into local file names before reaching the command, so hf download <repo> --include "*.json" run in a folder containing a .json file silently downloaded nothing. Arguments are no longer glob-expanded on Windows.
• snapshot_download now warns when allow or ignore patterns match no files, and hf-xet is installed on Windows ARM64.

Breaking Changes and Open Questions

The notes say two behavior changes are listed under breaking changes. The first is the snapshot default described above. The second is that load_torch_model now raises FileNotFoundError instead of ValueError when the checkpoint path does not exist, and model_index_to_eval_results raises ValueError on an empty list.

The sources do not say how many downloads were affected by the hf_xet race, or how often it occurred outside the multi-threaded test. The release notes describe the affected case only as a fresh process making its first concurrent download calls. The test figures above come from the pull request author, not from an independent reproduction.