●Change8

Migrating to HuggingFace Hub v1.16.0

Version v1.16.0 introduces 3 breaking changes. This guide details how to update your code.

Released: 5/21/2026

3
Breaking Changes
3
Migration Steps
12
Affected Symbols

⚠️ Check Your Code

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

BucketUrl.handleBucketUrl.uriVolume.to_hf_handle()Volume.to_uri()HfFileSystemparse_hf_uriparse_hf_mountis_hf_uriHfUriErrorclient.feature_extractionclient.text_to_speechclient.text_to_video

Breaking Changes

●Issue #1

BucketUrl.handle has been renamed to BucketUrl.uri (type changed from str to HfUri, use .to_uri() for the string form).

●Issue #2

Volume.to_hf_handle() has been renamed to Volume.to_uri().

●Issue #3

Single-segment repo IDs (e.g. gpt2) are no longer supported in HfFileSystem paths or CLI -v flags; you must use the namespace/name format instead.

Migration Steps

  1. 1
    If using BucketUrl.handle, rename usage to BucketUrl.uri and use .to_uri() if the string form is required.
  2. 2
    If using Volume.to_hf_handle(), rename usage to Volume.to_uri().
  3. 3
    Ensure all single-segment repository IDs used in HfFileSystem paths or CLI -v flags are updated to the namespace/name format (e.g., change gpt2 to openai/gpt2).

Release Summary

This release introduces broad multimodal support for Together Inference Providers and centralizes hf:// URI parsing logic for consistency. Security and usability enhancements include hardened token file permissions and a new global CLI flag to prevent table truncation.

Need More Details?

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

View Full Changelog