Patch release to make hf-xet optional. More context in #3079 and #3078.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.31.1...v0.31.2
We're introducing blazingly fast LoRA inference powered by fal.ai and Replicate through Hugging Face Inference Providers! You can use any compatible LoRA available on the Hugging Face Hub and get generations at lightning fast speed ⚡
from huggingface_hub import InferenceClient
client = InferenceClient(provider="fal-ai") # or provider="replicate"
# output is a PIL.Image object
image = client.text_to_image(
"a boy and a girl looking out of a window with a cat perched on the window sill. There is a bicycle parked in front of them and a plant with flowers to the right side of the image. The wall behind them is visible in the background.",
model="openfree/flux-chatgpt-ghibli-lora",
)
auto mode for provider selectionYou can now automatically select a provider for a model using auto mode — it will pick the first available provider based on your preferred order set in https://hf.co/settings/inference-providers.
from huggingface_hub import InferenceClient
# will select the first provider available for the model, sorted by your order.
client = InferenceClient(provider="auto")
completion = client.chat.completions.create(
model="Qwen/Qwen3-235B-A22B",
messages=[
{
"role": "user",
"content": "What is the capital of France?"
}
],
)
print(completion.choices[0].message)
⚠️ Note: This is now the default value for the provider argument. Previously, the default was hf-inference, so this change may be a breaking one if you're not specifying the provider name when initializing InferenceClient or AsyncInferenceClient.
provider="auto" by @julien-c in #3011We added support for feature extraction (embeddings) inference with sambanova provider.
HF Inference API provider is now fully integrated as an Inference Provider, this means it only supports a predefined list of deployed models, selected based on popularity. Cold-starting arbitrary models from the Hub is no longer supported — if a model isn't already deployed, it won’t be available via HF Inference API.
Miscellaneous improvements and some bug fixes:
✅ Of course, all of those inference changes are available in the AsyncInferenceClient async equivalent 🤗
Thanks to @bpronan's PR, Xet now supports uploading byte arrays:
from huggingface_hub import upload_file
file_content = b"my-file-content"
repo_id = "username/model-name" # `hf-xet` should be installed and Xet should be enabled for this repo
upload_file(
path_or_fileobj=file_content,
repo_id=repo_id,
)
Additionally, we’ve added documentation for environment variables used by hf-xet to optimize file download/upload performance — including options for caching (HF_XET_CHUNK_CACHE_SIZE_BYTES), concurrency (HF_XET_NUM_CONCURRENT_RANGE_GETS), high-performance mode (HF_XET_HIGH_PERFORMANCE), and sequential writes (HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY).
Miscellaneous improvements:
We added HTTP download support for files larger than 50GB — enabling more reliable handling of large file downloads.
We also added dynamic batching to upload_large_folder, replacing the fixed 50-files-per-commit rule with an adaptive strategy that adjusts based on commit success and duration — improving performance and reducing the risk of hitting the commits rate limit on large repositories.
We added support for new arguments when creating or updating Hugging Face Inference Endpoints.
provider argument in InferenceClient and AsyncInferenceClient is now "auto" instead of "hf-inference" (HF Inference API). This means provider selection will now follow your preferred order set in your inference provider settings.
If your code relied on the previous default ("hf-inference"), you may need to update it explicitly to avoid unexpected behavior.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}.hf_xet min version to 1.0.0 + make it required dep on 64 bits by @hanouticelina in #2971The following contributors have made significant changes to the library over the last release:
Fixing some InferenceClient-related bugs:
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.30.1...v0.30.2
Patch release to fix https://github.com/huggingface/huggingface_hub/issues/2967.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.30.0...v0.30.1
This might just be our biggest update in the past two years! Xet is a groundbreaking new protocol for storing large objects in Git repositories, designed to replace Git LFS. Unlike LFS, which deduplicates files, Xet operates at the chunk level—making it a game-changer for AI builders collaborating on massive models and datasets. Our Python integration is powered by xet-core, a Rust-based package that handles all the low-level details.
You can start using Xet today by installing the optional dependency:
pip install -U huggingface_hub[hf_xet]With that, you can seamlessly download files from Xet-enabled repositories! And don’t worry—everything remains fully backward-compatible if you’re not ready to upgrade yet.
Blog post: Xet on the Hub
Docs: Storage backends → Xet
[!TIP]
Want to store your own files with Xet? We’re gradually rolling out support on the Hugging Face Hub, sohf_xetuploads may need to be enabled for your repo. Join the waitlist to get onboarded soon!
This is the result of collaborative work by @bpronan, @hanouticelina, @rajatarya, @jsulz, @assafvayner, @Wauplin, + many others on the infra/Hub side!
xetEnabled as an expand property by @hanouticelina in #2907The InferenceClient has received significant updates and improvements in this release, making it more robust and easy to work with.
We’re thrilled to introduce Cerebras and Cohere as official inference providers! This expansion strengthens the Hub as the go-to entry point for running inference on open-weight models.
Novita is now our 3rd provider to support text-to-video task after Fal.ai and Replicate:
from huggingface_hub import InferenceClient
client = InferenceClient(provider="novita")
video = client.text_to_video(
"A young man walking on the street",
model="Wan-AI/Wan2.1-T2V-14B",
)
It is now possible to centralize billing on your organization rather than individual accounts! This helps companies managing their budget and setting limits at a team level. Organization must be subscribed to Enterprise Hub.
from huggingface_hub import InferenceClient
client = InferenceClient(provider="fal-ai", bill_to="openai")
image = client.text_to_image(
"A majestic lion in a fantasy forest",
model="black-forest-labs/FLUX.1-schnell",
)
image.save("lion.png")
Handling long-running inference tasks just got easier! To prevent request timeouts, we’ve introduced asynchronous calls for text-to-video inference. We are expecting more providers to leverage the same structure soon, ensuring better robustness and developer-experience.
Miscellaneous improvements:
InferenceClient docstring to reflect that token=False is no longer accepted by @abidlabs in #2853provider parameter by @hanouticelina in #2949This release also includes several other notable features and improvements.
It's now possible to pass a path with wildcard to the upload command instead of passing --include=... option:
huggingface-cli upload my-cool-model *.safetensors
Deploying an Inference Endpoint from the Model Catalog just got 100x easier! Simply select which model to deploy and we handle the rest to guarantee the best hardware and settings for your dedicated endpoints.
from huggingface_hub import create_inference_endpoint_from_catalog
endpoint = create_inference_endpoint_from_catalog("unsloth/DeepSeek-R1-GGUF")
endpoint.wait()
endpoint.client.chat_completion(...)
The ModelHubMixin got two small updates:
config until now)You can now sort by name, size, last updated and last used where using the delete-cache command:
huggingface-cli delete-cache --sort=size--sort arg to delete-cache to sort by size by @AlpinDale in #2815Since end 2024, it is possible to manage the LFS files stored in a repo from the UI (see docs). This release makes it possible to do the same programmatically. The goal is to enable users to free-up some storage space in their private repositories.
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> lfs_files = api.list_lfs_files("username/my-cool-repo")
# Filter files files to delete based on a combination of `filename`, `pushed_at`, `ref` or `size`.
# e.g. select only LFS files in the "checkpoints" folder
>>> lfs_files_to_delete = (lfs_file for lfs_file in lfs_files if lfs_file.filename.startswith("checkpoints/"))
# Permanently delete LFS files
>>> api.permanently_delete_lfs_files("username/my-cool-repo", lfs_files_to_delete)
[!WARNING] This is a power-user tool to use carefully. Deleting LFS files from a repo is a non-revertible action.
labels has been removed from InferenceClient.zero_shot_classification and InferenceClient.zero_shot_image_classification tasks in favor of candidate_labels. There has been a proper deprecation warning for that.
Thanks to the work previously introduced by the diffusers team, we've published a GitHub Action that runs code style tooling on demand on Pull Requests, making the life of contributors and reviewers easier.
Other minor updates:
The following contributors have made significant changes to the library over the last release:
InferenceClient docstring to reflect that token=False is no longer accepted (#2853)--sort arg to delete-cache to sort by size (#2815)Added client-side support for Cerebras and Cohere providers for upcoming official launch on the Hub.
Cerebras: https://github.com/huggingface/huggingface_hub/pull/2901. Cohere: https://github.com/huggingface/huggingface_hub/pull/2888.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.29.2...v0.29.3
This patch release includes two fixes:
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.29.1...v0.29.2
This patch release includes two fixes:
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.29.0...v0.29.1
We’re thrilled to announce the addition of three more outstanding serverless Inference Providers to the Hugging Face Hub: Fireworks AI, Hyperbolic, Nebius AI Studio, and Novita. These providers join our growing ecosystem, enhancing the breadth and capabilities of serverless inference directly on the Hub’s model pages. This release adds official support for these 3 providers, making it super easy to use a wide variety of models with your preferred providers.
See our announcement blog for more details: https://huggingface.co/blog/new-inference-providers.
Note that Black Forest Labs is not yet supported on the Hub. Once we announce it, huggingface_hub 0.29.0 will automatically support it.
base_url if provided by @Wauplin in #2805extra_parameters to extra_body by @hanouticelina in #2821None.
HF_DEBUG environment variable for debugging/reproducibility by @Wauplin in #2819The following contributors have made significant changes to the library over the last release:
Release 0.28.0 introduced a bug making it impossible to set a HF_ENDPOINT env variable with a value with a subpath. This has been fixed in https://github.com/huggingface/huggingface_hub/pull/2807.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.28.0...v0.28.1
The InferenceClient now supports third-party providers, offering a unified interface to run inference across multiple services while leveraging models from the Hugging Face Hub. This update enables developers to:
A list of supported third-party providers can be found here.
Example of text-to-image inference with Replicate:
>>> from huggingface_hub import InferenceClient
>>> replicate_client = InferenceClient(
... provider="replicate",
... api_key="my_replicate_api_key", # Using your personal Replicate key
)
>>> image = replicate_client.text_to_image(
... "A cyberpunk cat hacking neural networks",
... model="black-forest-labs/FLUX.1-schnell"
)
>>> image.save("cybercat.png")
Another example of chat completion with Together AI:
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="together", # Use Together AI provider
... api_key="<together_api_key>", # Pass your Together API key directly
... )
>>> client.chat_completion(
... model="deepseek-ai/DeepSeek-R1",
... messages=[{"role": "user", "content": "How many r's are there in strawberry?"}],
... )
When using external providers, you can choose between two access modes: either use the provider's native API key, as shown in the examples above, or route calls through Hugging Face infrastructure (billed to your HF account):
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(
... provider="fal-ai",
... token="hf_****" # Your Hugging Face token
)
⚠️ Parameters availability may vary between providers - check provider documentation. 🔜 New providers/models/tasks will be added iteratively in the future. 👉 You can find a list of supported tasks per provider and more details here.
- [InferenceClient] Add third-party providers support by @hanouticelina in #2757
- Unified
prepare_requestmethod + class-based providers by @Wauplin in #2777- [InferenceClient] Support proxy calls for 3rd party providers by @hanouticelina in #2781
- [InferenceClient] Add
text-to-videotask and update supported tasks and models by @hanouticelina in #2786- Add type hints for providers by @Wauplin in #2788
- [InferenceClient] Update inference documentation by @hanouticelina in #2776
- Add text-to-video to supported tasks by @Wauplin in #2790
The following change aligns the client with server-side updates by adding new repositories properties: usedStorage and resourceGroup.
[HfApi] update list of repository properties following server side updates by @hanouticelina in #2728
Extends empty commit prevention to file copy operations, preserving clean version histories when no changes are made.
[HfApi] prevent empty commits when copying files by @hanouticelina in #2730
Thanks to @WizKnight, the hindi translation is much better!
Improved Hindi Translation in Documentation📝 by @WizKnight in #2697
The like endpoint has been removed to prevent misuse. You can still remove existing likes using the unlikeendpoint.
[HfApi] remove
likeendpoint by @hanouticelina in #2739
chat_completion()'s logit_bias as UNUSED by @hanouticelina in #2724py.typed to be compliant with PEP-561 again by @hanouticelina in #2752typing.get_type_hints call on a ModelHubMixin by @aliberts in #2729CardData.get() to respect default values when None by @hanouticelina in #2770RepoCard test on Windows by @hanouticelina in #2774Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.27.0...v0.27.1
See #2729 for more details.
DDUF (DDUF's Diffusion Unified Format) is a single-file format for diffusion models that aims to unify the different model distribution methods and weight-saving formats by packaging all model components into a single file. We will soon have a detailed documentation for that.
The huggingface_hub library now provides tooling to handle DDUF files in Python. It includes helpers to read and export DDUF files, and built-in rules to validate file integrity.
>>> from huggingface_hub import export_folder_as_dduf
# Export "path/to/FLUX.1-dev" folder as a DDUF file
>>> export_folder_as_dduf("FLUX.1-dev.dduf", folder_path="path/to/FLUX.1-dev")
>>> import json
>>> import safetensors.torch
>>> from huggingface_hub import read_dduf_file
# Read DDUF metadata (only metadata is loaded, lightweight operation)
>>> dduf_entries = read_dduf_file("FLUX.1-dev.dduf")
# Returns a mapping filename <> DDUFEntry
>>> dduf_entries["model_index.json"]
DDUFEntry(filename='model_index.json', offset=66, length=587)
# Load the `model_index.json` content
>>> json.loads(dduf_entries["model_index.json"].read_text())
{'_class_name': 'FluxPipeline', '_diffusers_version': '0.32.0.dev0', '_name_or_path': 'black-forest-labs/FLUX.1-dev', 'scheduler': ['diffusers', 'FlowMatchEulerDiscreteScheduler'], 'text_encoder': ['transformers', 'CLIPTextModel'], 'text_encoder_2': ['transformers', 'T5EncoderModel'], 'tokenizer': ['transformers', 'CLIPTokenizer'], 'tokenizer_2': ['transformers', 'T5TokenizerFast'], 'transformer': ['diffusers', 'FluxTransformer2DModel'], 'vae': ['diffusers', 'AutoencoderKL']}
# Load VAE weights using safetensors
>>> with dduf_entries["vae/diffusion_pytorch_model.safetensors"].as_mmap() as mm:
... state_dict = safetensors.torch.load(mm)
⚠️ Note that this is a very early version of the parser. The API and implementation can evolve in the near future. 👉 More details about the API in the documentation here.
DDUF parser v0.1 by @Wauplin in #2692
Following the introduction of the torch serialization module in 0.22.* and the support of saving torch state dict to disk in 0.24.*, we now provide helpers to load torch state dicts from disk.
By centralizing these functionalities in huggingface_hub, we ensure a consistent implementation across the HF ecosystem while allowing external libraries to benefit from standardized weight handling.
>>> from huggingface_hub import load_torch_model, load_state_dict_from_file
# load state dict from a single file
>>> state_dict = load_state_dict_from_file("path/to/weights.safetensors")
# Directly load weights into a PyTorch model
>>> model = ... # A PyTorch model
>>> load_torch_model(model, "path/to/checkpoint")
More details in the serialization package reference.
[Serialization] support loading torch state dict from disk by @hanouticelina in #2687
We added a flag to save_torch_state_dict() helper to properly handle model saving in distributed environments, aligning with existing implementations across the Hugging Face ecosystem:
[Serialization] Add is_main_process argument to save_torch_state_dict() by @hanouticelina in #2648
A bug with shared tensor handling reported in transformers#35080 has been fixed:
add argument to pass shared tensors keys to discard by @hanouticelina in #2696
The following changes align the client with server-side updates in how security metadata is handled and exposed in the API responses. In particular, The repository security status returned by HfApi().model_info() is now available in the security_repo_status field:
from huggingface_hub import HfApi
api = HfApi()
model = api.model_info("your_model_id", securityStatus=True)
# get security status info of your model
- security_info = model.securityStatus
+ security_info = model.security_repo_status
- Update how file's security metadata is retrieved following changes in the API response by @hanouticelina in #2621
- Expose repo security status field in ModelInfo by @hanouticelina in #2639
Thanks to @miaowumiaomiaowu, more documentation is now available in Chinese! And thanks @13579606 for reviewing these PRs. Check out the result here.
:memo:Translating docs to Simplified Chinese by @miaowumiaomiaowu in #2689, #2704 and #2705.
A few breaking changes have been introduced:
RepoCardData serialization now preserves None values in nested structures.InferenceClient.image_to_image() now takes a target_size argument instead of height and width arguments. This is has been reflected in the InferenceClient async equivalent as well.InferenceClient.table_question_answering() no longer accepts a parameter argument. This is has been reflected in the InferenceClient async equivalent as well.list_metrics() has been removed from HfApi.
- Do not remove None values in RepoCardData serialization by @Wauplin in #2626
- manually update chat completion params by @hanouticelina in #2682
- [Bot] Update inference types #2688
- rm list_metrics by @julien-c in #2702
Some deprecations have been introduced as well:
is_write_action in build_hf_headers(), write_permission=True in login methods. get_token_permission has been deprecated as well.labels argument is deprecated in InferenceClient.zero_shot_classification() and InferenceClient.image_zero_shot_classification(). This is has been reflected in the InferenceClient async equivalent as well.
- Deprecate is_write_action and write_permission=True when login by @Wauplin in #2632
- Fix and deprecate get_token_permission by @Wauplin in #2631
- [Inference Client] fix param docstring and deprecate labels param in zero-shot classification tasks by @hanouticelina in #2668
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.26.3...v0.26.5
See #2696 for more details.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.26.2...v0.26.3
See https://github.com/huggingface/huggingface_hub/pull/2683 for more details.
This patch release includes updates to align with recent API response changes:
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.26.1...v0.26.2
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.26.0...v0.26.1
See https://github.com/huggingface/huggingface_hub/pull/2620 for more details.
Managing fine-grained access tokens locally just became much easier and more efficient! Fine-grained tokens let you create tokens with specific permissions, making them especially useful in production environments or when working with external organizations, where strict access control is essential.
To make managing these tokens easier, we've added a ✨ new set of CLI commands ✨ that allow you to handle them programmatically:
login() command with each token:huggingface-cli loginhuggingface-cli auth switchhuggingface-cli auth listhuggingface-cli logout [--token-name TOKEN_NAME]✅ Nothing changes if you are using the HF_TOKEN environment variable as it takes precedence over the token set via the CLI. More details in the documentation. 🤗
Conversational vision-language models inference is now supported with InferenceClient's chat completion!
from huggingface_hub import InferenceClient
# works with remote url or base64 encoded url
image_url ="https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
client = InferenceClient("meta-llama/Llama-3.2-11B-Vision-Instruct")
output = client.chat.completions.create(
messages=[
{
"role": "user",
"content": [
{
"type": "image_url",
"image_url": {"url": image_url},
},
{
"type": "text",
"text": "Describe this image in one sentence.",
},
],
},
],
)
print(output.choices[0].message.content)
#A determine figure of Lady Liberty stands tall, holding a torch aloft, atop a pedestal on an island.
You can now pass additional inference parameters to more task methods in the InferenceClient, including: image_classification, text_classification, image_segmentation, object_detection, document_question_answering and more!
For more details, visit the InferenceClient reference guide.
✅ Of course, all of those changes are also available in the AsyncInferenceClient async equivalent 🤗
update_repo_settings can now be used to switch visibility status of a repo. This is a drop-in replacement for update_repo_visibility which is deprecated and will be removed in version v0.29.0.
- update_repo_visibility(repo_id, private=True)
+ update_repo_settings(repo_id, private=True)
📄 Daily papers API is now supported in huggingface_hub, enabling you to search for papers on the Hub and retrieve detailed paper information.
>>> from huggingface_hub import HfApi
>>> api = HfApi()
# List all papers with "attention" in their title
>>> api.list_papers(query="attention")
# Get paper information for the "Attention Is All You Need" paper
>>> api.paper_info(id="1706.03762")
Efforts from the Tamil-speaking community to translate guides and package references to TM! Check out the result here.
A few breaking changes have been introduced:
cached_download(), url_to_filename(), filename_to_url() methods are now completely removed. From now on, you will have to use hf_hub_download() to benefit from the new cache layout.legacy_cache_layout argument from hf_hub_download() has been removed as well.These breaking changes have been announced with a regular deprecation cycle.
Also, any templating-related utility has been removed from huggingface_hub. Client side templating is not necessary now that all conversational text-generation models in InferenceAPI are served with TGI.
Prepare for release 0.26 by @hanouticelina in #2579 Remove templating utility by @Wauplin in #2611
i18n by @SauravMaheshkar in #2566state_dict by @SunMarc in #2591local_dir is provided. by @hanouticelina in #2592The following contributors have made significant changes to the library over the last release:
i18n (#2566)Full Changelog : v0.25.1...v0.25.2 For more details, refer to the related PR https://github.com/huggingface/huggingface_hub/pull/2592
Full Changelog : v0.25.0...v0.25.1
For more details, refer to the related PR #2558