●Change8

Migrating to HuggingFace Hub v0.31.0

Version v0.31.0 introduces 2 breaking changes. This guide details how to update your code.

Released: 5/6/2025

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:

InferenceClientAsyncInferenceClientclient.text_to_imageclient.chat.completions.createupload_filehf-xet

Breaking Changes

●Issue #1

The default value of the 'provider' argument in InferenceClient and AsyncInferenceClient is now "auto" instead of "hf-inference" (HF Inference API). If your code relied on the previous default, you must explicitly set provider="hf-inference" or use provider="auto" if you rely on provider ordering.

●Issue #2

HF Inference API Routing Update: The inference URL path for 'feature-extraction' and 'sentence-similarity' tasks has changed from https://router.huggingface.co/hf-inference/pipeline/{task}/{model} to https://router.huggingface.co/hf-inference/models/{model}/pipeline/{task}.

Migration Steps

  1. 1
    If your code relied on the default provider being "hf-inference", update your InferenceClient or AsyncInferenceClient initialization to explicitly set provider="hf-inference" or rely on the new default provider="auto" if you have configured provider preferences.
  2. 2
    If you are using HF Inference API for 'feature-extraction' or 'sentence-similarity' tasks, update any hardcoded routing logic to use the new path structure: https://router.huggingface.co/hf-inference/models/{model}/pipeline/{task}.

Release Summary

This release introduces major enhancements to Inference Providers, adding support for LoRA inference via fal.ai and Replicate, and enabling 'auto' provider selection as the new default. Additionally, Xet uploads now support byte arrays, and large file downloads (>50GB) are more reliable.

Need More Details?

View the full release notes and all changes for HuggingFace Hub v0.31.0.

View Full Changelog