NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #89 most downloaded on PyPI
Client library to download and publish models, datasets and other repos on the huggingface.co hub
Last release 7 days ago
24 Sep 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 56 of the last 60 stable releases
7 versions withdrawn
withdrawn after publishing
6 years old
328 releases · first in 2020
One column per quarter.
Nothing published for this version
Nothing published for this version
Fix file corruption when server ignores Range header on download retry. Full details in https://github.com/huggingface/huggingface_hub/pull/3778 by @X
Fix file corruption when server ignores Range header on download retry. Full details in https://github.com/huggingface/huggingface_hub/pull/3778 by @XciD.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.36.1...v0.36.2
Nothing published for this version
[Workflow] security fix by @glegendre01 in #3383
This is the final minor release before v1.0.0. This release focuses on performance optimizations to HfFileSystem and adds a new get_organization_overview API endpoint.
We'll continue to release security patches as needed, but v0.37 will not happen. The next release will be 1.0.0. We’re also deeply grateful to the entire Hugging Face community for their feedback, bug reports, and suggestions that have shaped this library.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.35.0...v0.36.0
HfFileSystemMajor optimizations have been implemented in HfFileSystem:
fs instance. This is particularily useful when streaming datasets in a distributed training environment. Each worker won't have to rebuild their cache anymoreListing files with .glob() has been greatly optimized:
from huggingface_hub import HfFileSystem
HfFileSystem().glob("datasets/HuggingFaceFW/fineweb-edu/data/*/*")
# Before: ~100 /tree calls (one per subdirectory)
# Now: 1 /tree call
maxdepth: do less /tree calls in glob() by @lhoestq in #3389Minor updates:
HfApiIt is now possible to get high-level information about an organization, the same way it is already possible to do with users:
>>> from huggingface_hub import get_organization_overview
>>> get_organization_overview("huggingface")
Organization(
avatar_url='https://cdn-avatars.huggingface.co/v1/production/uploads/1583856921041-5dd96eb166059660ed1ee413.png',
name='huggingface',
fullname='Hugging Face',
details='The AI community building the future.',
is_verified=True,
is_following=True,
num_users=198,
num_models=164, num_spaces=96,
num_datasets=1043,
num_followers=64814
)
sentence_similarity docstring by @tolgaakar in #3374ty quality by @hanouticelina in #3441The following contributors have made changes to the library over the last release. Thank you!
sentence_similarity docstring (#3374) (#3375)Nothing published for this version
This release includes two bug fixes:
This release includes two bug fixes:
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.35.2...v0.35.3
Z.ai is now officially an Inference Provider on the Hub. See full documentation here: https://huggingface.co/docs/inference-providers/providers/zai-or
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.35.1...v0.35.2
New inference provider! :fire:
Z.ai is now officially an Inference Provider on the Hub. See full documentation here: https://huggingface.co/docs/inference-providers/providers/zai-org.
from huggingface_hub import InferenceClient
client = InferenceClient(provider="zai-org")
completion = client.chat.completions.create(
model="zai-org/GLM-4.5",
messages=[{"role": "user", "content": "What is the capital of France?"}],
)
print("\nThinking:")
print(completion.choices[0].message.reasoning_content)
print("\nOutput:")
print(completion.choices[0].message.content)
Thinking:
Okay, the user is asking about the capital of France. That's a pretty straightforward geography question.
Hmm, I wonder if this is just a casual inquiry or if they need it for something specific like homework or travel planning. The question is very basic though, so probably just general knowledge.
Paris is definitely the correct answer here. It's been the capital for centuries, since the Capetian dynasty made it the seat of power. Should I mention any historical context? Nah, the user didn't ask for details - just the capital.
I recall Paris is also France's largest city and major cultural hub. But again, extra info might be overkill unless they follow up. Better keep it simple and accurate.
The answer should be clear and direct: "Paris". No need to overcomplicate a simple fact. If they want more, they'll ask.
Output:
The capital of France is **Paris**.
Paris has been the political and cultural center of France for centuries, serving as the seat of government, the residence of the President (Élysée Palace), and home to iconic landmarks like the Eiffel Tower, the Louvre Museum, and Notre-Dame Cathedral. It is also France's largest city and a global hub for art, fashion, gastronomy, and history.
Misc:
Do not retry on 429 (only on 5xx) https://github.com/huggingface/huggingface_hub/pull/3377
strict dataclasses https://github.com/huggingface/huggingface_hub/pull/3376Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.35.0...v0.35.1
Deprecate library/tags/task/... filtering in list_models by @Wauplin in #3318
In v0.34.0 release, we announced Jobs, a new way to run compute on the Hugging Face Hub. In this new release, we are announcing Scheduled Jobs to run Jobs on a regular basic. Think "cron jobs running on GPU".
This comes with a fully-fledge CLI:
hf jobs scheduled run @hourly ubuntu echo hello world
hf jobs scheduled run "0 * * * *" ubuntu echo hello world
hf jobs scheduled ps -a
hf jobs scheduled inspect <id>
hf jobs scheduled delete <id>
hf jobs scheduled suspend <id>
hf jobs scheduled resume <id>
hf jobs scheduled uv run @weekly train.py
It is now possible to run a command with uv run:
hf jobs uv run --with lighteval -s HF_TOKEN lighteval endpoint inference-providers "model_name=openai/gpt-oss-20b,provider=groq" "lighteval|gsm8k|0|0"
hf jobs uv run by @lhoestq in #3303Some other improvements have been added to the existing Jobs API for a better UX.
And finally, Jobs documentation has been updated with new examples (and some fixes):
In addition to the Scheduled Jobs, some improvements have been added to the hf CLI.
Two new partners have been integrated to Inference Providers: Scaleway and PublicAI! (as part of releases 0.34.5 and 0.34.6).
Image to video is now supported in the InferenceClient:
from huggingface_hub import InferenceClient
client = InferenceClient(provider="fal-ai")
video = client.image_to_video(
"cat.png",
prompt="The cat starts to dance",
model="Wan-AI/Wan2.2-I2V-A14B",
)
Header content-type is now correctly set when sending an image or audio request (e.g. for image-to-image task). It is inferred either from the filename or the URL provided by the user. If user is directly passing raw bytes, the content-type header has to be set manually.
A .reasoning field has been added to the Chat Completion output. This is used by some providers to return reasoning tokens separated from the .content stream of tokens.
tiny-agents now handles AGENTS.md instruction file (see https://agents.md/).
Tools filtering has already been improved to avoid loading non-relevant tools from an MCP server:
HF_HUB_DISABLE_XET in the environment dump by @hanouticelina in #3290apps as a parameter to HfApi.list_models by @anirbanbasu in #3322ty type checker by @hanouticelina in #3294tycheck quality by @hanouticelina in #3320is_jsonable if circular reference by @Wauplin in #3348The following contributors have made changes to the library over the last release. Thank you!
apps as a parameter to HfApi.list_models (#3322)Nothing published for this version
Nothing published for this version
> All supported PublicAI models can be found here.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.34.5...v0.34.6
[!Tip] All supported PublicAI models can be found here.
Public AI Inference Utility is a nonprofit, open-source project building products and organizing advocacy to support the work of public AI model builders like the Swiss AI Initiative, AI Singapore, AI Sweden, and the Barcelona Supercomputing Center. Think of a BBC for AI, a public utility for AI, or public libraries for AI.
from huggingface_hub import InferenceClient
client = InferenceClient(provider="publicai")
completion = client.chat.completions.create(
model="swiss-ai/Apertus-70B-Instruct-2509",
messages=[{"role": "user", "content": "What is the capital of Switzerland?"}],
)
print(completion.choices[0].message.content)
> All supported Scaleway models can be found here. For more details, check out its documentation page.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.34.4...v0.34.5
[!Tip] All supported Scaleway models can be found here. For more details, check out its documentation page.
Scaleway is a European cloud provider, serving latest LLM models through its Generative APIs alongside a complete cloud ecosystem.
from huggingface_hub import InferenceClient
client = InferenceClient(provider="scaleway")
completion = client.chat.completions.create(
model="Qwen/Qwen3-235B-A22B-Instruct-2507",
messages=[
{
"role": "user",
"content": "What is the capital of France?"
}
],
)
print(completion.choices[0].message)
Biggest update is the support of Image-To-Video task with inference provider Fal AI
Biggest update is the support of Image-To-Video task with inference provider Fal AI
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> video = client.image_to_video("cat.jpg", model="Wan-AI/Wan2.2-I2V-A14B", prompt="turn the cat into a tiger")
>>> with open("tiger.mp4", "wb") as f:
... f.write(video)
And some quality of life improvements:
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.34.3...v0.34.4
[Jobs] Update uv image #3270 by @lhoestq
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.34.2...v0.34.3
bug fix: only extend path on window sys in #3265 by @vealocia
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.34.1...v0.34.2
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.34.0...v0.34.1
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.34.0...v0.34.1
…huggingface-cli remains available without any breaking change, but is officially deprecated. We took the opportunity update the syntax to a more moder…
We're thrilled to introduce a powerful new command-line interface for running and managing compute jobs on Hugging Face infrastructure! With the new hf jobs command, you can now seamlessly launch, monitor, and manage jobs using a familiar Docker-like experience. Run any command in Docker images (from Docker Hub, Hugging Face Spaces, or your own custom images) on a variety of hardware including CPUs, GPUs, and TPUs - all with simple, intuitive commands.
Key features:
run, ps, logs, inspect, cancel) to run and manage jobsuv (experimental)All features are available both from Python (run_job, list_jobs, etc.) and the CLI (hf jobs).
Example usage:
# Run a Python script on the cloud
hf jobs run python:3.12 python -c "print('Hello from the cloud!')"
# Use a GPU
hf jobs run --flavor=t4-small --namespace=huggingface ubuntu nvidia-smi
# List your jobs
hf jobs ps
# Stream logs from a job
hf jobs logs <job-id>
# Inspect job details
hf jobs inspect <job-id>
# Cancel a running job
hf jobs cancel <job-id>
# Run a UV script (experimental)
hf jobs uv run my_script.py --flavor=a10g-small --with=trl
You can also pass environment variables and secrets, select hardware flavors, run jobs in organizations, and use the experimental uv runner for Python scripts with inline dependencies.
Check out the Jobs guide for more examples and details.
hf! (formerly huggingface-cli)Glad to announce a long awaited quality-of-life improvement: the Hugging Face CLI has been officially renamed from huggingface-cli to hf! The legacy huggingface-cli remains available without any breaking change, but is officially deprecated. We took the opportunity update the syntax to a more modern command format hf <resource> <action> [options] (e.g. hf auth login, hf repo create, hf jobs run).
Run hf --help to know more about the CLI options.
✗ hf --help
usage: hf <command> [<args>]
positional arguments:
{auth,cache,download,jobs,repo,repo-files,upload,upload-large-folder,env,version,lfs-enable-largefiles,lfs-multipart-upload}
hf command helpers
auth Manage authentication (login, logout, etc.).
cache Manage local cache directory.
download Download files from the Hub
jobs Run and manage Jobs on the Hub.
repo Manage repos on the Hub.
repo-files Manage files in a repo on the Hub.
upload Upload a file or a folder to the Hub. Recommended for single-commit uploads.
upload-large-folder
Upload a large folder to the Hub. Recommended for resumable uploads.
env Print information about the environment.
version Print information about the hf version.
options:
-h, --help show this help message and exit
Added support for image-to-image task in the InferenceClient for Replicate and fal.ai providers, allowing quick image generation using FLUX.1-Kontext-dev:
from huggingface_hub import InferenceClient
client = InferenceClient(provider="fal-ai")
client = InferenceClient(provider="replicate")
with open("cat.png", "rb") as image_file:
input_image = image_file.read()
# output is a PIL.Image object
image = client.image_to_image(
input_image,
prompt="Turn the cat into a tiger.",
model="black-forest-labs/FLUX.1-Kontext-dev",
)
image-to-image support for Replicate provider by @hanouticelina in #3188image-to-image support for fal.ai provider by @hanouticelina in #3187In addition to this, it is now possible to directly pass a PIL.Image as input to the InferenceClient.
tiny-agents got a nice update to deal with environment variables and secrets. We've also changed its input format to follow more closely the config format from VSCode. Here is an up to date config to run Github MCP Server with a token:
{
"model": "Qwen/Qwen2.5-72B-Instruct",
"provider": "nebius",
"inputs": [
{
"type": "promptString",
"id": "github-personal-access-token",
"description": "Github Personal Access Token (read-only)",
"password": true
}
],
"servers": [
{
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"-e",
"GITHUB_TOOLSETS=repos,issues,pull_requests",
"ghcr.io/github/github-mcp-server"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github-personal-access-token}"
}
}
]
}
InferenceClient and tiny-agents got a few quality of life improvements and bug fixes:
Integration of Xet is now stable and production-ready. A majority of file transfer are now handled using this protocol on new repos. A few improvements have been shipped to ease developer experience during uploads:
Documentation has already been written to explain better the protocol and its options:
healthRoute instead of GET / to check status by @mfuntowicz in #3165expand argument when listing files in repos by @lhoestq in #3195libcst incompatibility with Python 3.13 by @hanouticelina in #3251Nothing published for this version
Fix: "UserWarning: ... sessions are still open..." when streaming with AsyncInferenceClient https://github.com/huggingface/huggingface_hub/pull/3252
AsyncInferenceClient https://github.com/huggingface/huggingface_hub/pull/3252Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.33.4...v0.33.5
Omit parameters in default tools of tiny-agent https://github.com/huggingface/huggingface_hub/pull/3214
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.33.3...v0.33.4
Update tiny-agents example #3205
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.33.2...v0.33.3
[Tiny-Agent] Switch to VSCode MCP format + fix headers handling #3166 by @Wauplin
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.33.1...v0.33.2
Breaking changes:
Example of agent.json:
{
"model": "Qwen/Qwen2.5-72B-Instruct",
"provider": "nebius",
"inputs": [
{
"type": "promptString",
"id": "hf-token",
"description": "Token for Hugging Face API access",
"password": true
}
],
"servers": [
{
"type": "http",
"url": "https://huggingface.co/mcp",
"headers": {
"Authorization": "Bearer ${input:hf-token}"
}
}
]
}
Find more examples in https://huggingface.co/datasets/tiny-agents/tiny-agents
This release introduces bug fixes for chat completion type compatibility and feature extraction parameters, enhanced message handling in tiny-agents,
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.33.0...v0.33.1
This release introduces bug fixes for chat completion type compatibility and feature extraction parameters, enhanced message handling in tiny-agents, and updated inference endpoint health check:
Featherless AI is a serverless AI inference provider with unique model loading and GPU orchestration abilities that makes an exceptionally large catal
Featherless AI is a serverless AI inference provider with unique model loading and GPU orchestration abilities that makes an exceptionally large catalog of models available for users. Providers often offer either a low cost of access to a limited set of models, or an unlimited range of models with users managing servers and the associated costs of operation. Featherless provides the best of both worlds offering unmatched model range and variety but with serverless pricing. Find the full list of supported models on the models page.
from huggingface_hub import InferenceClient
client = InferenceClient(provider="featherless-ai")
completion = client.chat.completions.create(
model="deepseek-ai/DeepSeek-R1-0528",
messages=[
{
"role": "user",
"content": "What is the capital of France?"
}
],
)
print(completion.choices[0].message)
At the heart of Groq's technology is the Language Processing Unit (LPU™), a new type of end-to-end processing unit system that provides the fastest inference for computationally intensive applications with a sequential component, such as Large Language Models (LLMs). LPUs are designed to overcome the limitations of GPUs for inference, offering significantly lower latency and higher throughput. This makes them ideal for real-time AI applications.
Groq offers fast AI inference for openly-available models. They provide an API that allows developers to easily integrate these models into their applications. It offers an on-demand, pay-as-you-go model for accessing a wide range of openly-available LLMs.
from huggingface_hub import InferenceClient
client = InferenceClient(provider="groq")
completion = client.chat.completions.create(
model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Describe this image in one sentence."},
{
"type": "image_url",
"image_url": {"url": "https://vagabundler.com/wp-content/uploads/2019/06/P3160166-Copy.jpg"},
},
],
}
],
)
print(completion.choices[0].message)
It is now possible to run tiny-agents using a local server e.g. llama.cpp. 100% local agents are right behind the corner!
Fixing some DX issues in the tiny-agents CLI.
tiny-agents cli exit issues by @Wauplin in #3125New translation from the Hindi-speaking community, for the community!
The following contributors have made significant changes to the library over the last release:
Nothing published for this version
Fix for wrongly saved upload_mode/remote_oid #3113
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.32.5...v0.32.6
Inject env var in headers + better type annotations #3142
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.32.4...v0.32.5
This release introduces bug fixes to tiny-agents and InferenceClient.question_answering:
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.32.3...v0.32.4
This release introduces bug fixes to tiny-agents and InferenceClient.question_answering:
asyncio.wait() does not accept bare coroutines #3135 by @hanouticelinaThis release introduces some improvements and bug fixes to tiny-agents:
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.32.2...v0.32.3
This release introduces some improvements and bug fixes to tiny-agents:
tiny-agents cli exit issues #3125[MCP] Add local/remote endpoint inference support https://github.com/huggingface/huggingface_hub/pull/3121
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.32.1...v0.32.2
Patch release to fix #3116 Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.32.0...v0.32.1
Patch release to fix #3116
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.32.0...v0.32.1
✨ The huggingface_hub library now includes an MCP Client, designed to empower Large Language Models (LLMs) with the ability to interact with external
✨ The huggingface_hub library now includes an MCP Client, designed to empower Large Language Models (LLMs) with the ability to interact with external Tools via Model Context Protocol (MCP). This client extends the InfrenceClient and provides a seamless way to connect LLMs to both local and remote tool servers!
pip install -U huggingface_hub[mcp]
In the following example, we use the Qwen/Qwen2.5-72B-Instruct model via the Nebius inference provider. We then add a remote MCP server, in this case, an SSE server which makes the Flux image generation tool available to the LLM:
import os
from huggingface_hub import ChatCompletionInputMessage, ChatCompletionStreamOutput, MCPClient
async def main():
async with MCPClient(
provider="nebius",
model="Qwen/Qwen2.5-72B-Instruct",
api_key=os.environ["HF_TOKEN"],
) as client:
await client.add_mcp_server(type="sse", url="https://evalstate-flux1-schnell.hf.space/gradio_api/mcp/sse")
messages = [
{
"role": "user",
"content": "Generate a picture of a cat on the moon",
}
]
async for chunk in client.process_single_turn_with_tools(messages):
# Log messages
if isinstance(chunk, ChatCompletionStreamOutput):
delta = chunk.choices[0].delta
if delta.content:
print(delta.content, end="")
# Or tool calls
elif isinstance(chunk, ChatCompletionInputMessage):
print(
f"\nCalled tool '{chunk.name}'. Result: '{chunk.content if len(chunk.content) < 1000 else chunk.content[:1000] + '...'}'"
)
if __name__ == "__main__":
import asyncio
asyncio.run(main())
For even simpler development, we now also offer a higher-level Agent class. These 'Tiny Agents' simplify creating conversational Agents by managing the chat loop and state, essentially acting as a user-friendly wrapper around MCPClient. It's designed to be a simple while loop built right on top of an MCPClient.
You can run these Agents directly from the command line:
> tiny-agents run --help
Usage: tiny-agents run [OPTIONS] [PATH] COMMAND [ARGS]...
Run the Agent in the CLI
╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ path [PATH] Path to a local folder containing an agent.json file or a built-in agent stored in the 'tiny-agents/tiny-agents' Hugging Face dataset │
│ (https://huggingface.co/datasets/tiny-agents/tiny-agents) │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
You can run these Agents using your own local configs or load them directly from the Hugging Face dataset tiny-agents.
This is an early version of the MCPClient, and community contributions are welcome 🤗
InferenceClient is also a MCPClient by @julien-c in #2986Thanks to @diadorer, feature extraction (embeddings) inference is now supported with Nebius provider!
We’re thrilled to introduce Nscale as an official inference provider! This expansion strengthens the Hub as the go-to entry point for running inference on open-weight models 🔥
We also fixed compatibility issues with structured outputs across providers by ensuring the InferenceClient follows the OpenAI API specs structured output.
We've introduced a new @strict decorator for dataclasses, providing robust validation capabilities to ensure data integrity both at initialization and during assignment. Here is a basic example:
from dataclasses import dataclass
from huggingface_hub.dataclasses import strict, as_validated_field
# Custom validator to ensure a value is positive
def positive_int(value: int):
if not value > 0:
raise ValueError(f"Value must be positive, got {value}")
class Config:
model_type: str
hidden_size: int = positive_int(default=16)
vocab_size: int = 32 # Default value
# Methods named `validate_xxx` are treated as class-wise validators
def validate_big_enough_vocab(self):
if self.vocab_size < self.hidden_size:
raise ValueError(f"vocab_size ({self.vocab_size}) must be greater than hidden_size ({self.hidden_size})")
config = Config(model_type="bert", hidden_size=24) # Valid
config = Config(model_type="bert", hidden_size=-1) # Raises StrictDataclassFieldValidationError
# `vocab_size` too small compared to `hidden_size`
config = Config(model_type="bert", hidden_size=32, vocab_size=16) # Raises StrictDataclassClassValidationError
This feature also includes support for custom validators, class-wise validation logic, handling of additional keyword arguments, and automatic validation based on type hints. Documentation can be found here.
@strict decorator for dataclass validation by @Wauplin in #2895This release brings also support for DTensor in _get_unique_id / get_torch_storage_size helpers, allowing transformers to seamlessly use save_pretrained with DTensor.
When creating an Endpoint, the default for scale_to_zero_timeout is now None, meaning endpoints will no longer scale to zero by default unless explicitly configured.
We've also introduced experimental helpers to manage OAuth within FastAPI applications, bringing functionality previously used in Gradio to a wider range of frameworks for easier integration.
We now have much more detailed documentation for Inference! This includes more detailed explanations and examples to clarify that the InferenceClient can also be effectively used with local endpoints (llama.cpp, vllm, MLX..etc).
api.endpoint to arguments for _get_upload_mode by @matthewgrossman in #3077read() by @lhoestq in #3080hf-xet optional by @hanouticelina in #3079huggingface-cli repo create command by @Wauplin in #3094The following contributors have made significant changes to the library over the last release:
Nothing published for this version
Nothing published for this version
This release includes some new features and bug fixes:
This release includes some new features and bug fixes:
strict decorators for runtime dataclass validation with custom and type-based checks. by @Wauplin in https://github.com/huggingface/huggingface_hub/pull/2895.DTensor support to _get_unique_id / get_torch_storage_size helpers, enabling transformers to use save_pretrained with DTensor. by @S1ro1 in https://github.com/huggingface/huggingface_hub/pull/3042.Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.31.2...v0.31.4
Nothing published for this version
Patch release to make hf-xet optional. More context in #3079 and #3078.
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
Nothing published for this version
[inference] Necessary breaking change: nest task-specific route inside of model route by @julien-c in #3044
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:
Nothing published for this version
Fixing some InferenceClient-related bugs:
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.
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
…of candidate_labels. There has been a proper deprecation warning for that.
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)Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Added client-side support for Cerebras and Cohere providers for upcoming official launch on the Hub.
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
Nothing published for this version
This patch release includes two fixes:
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:
This patch release includes two fixes:
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.29.0...v0.29.1
(misc) Deprecate some hf-inference specific features (wait-for-model header, can't override model's task, get_model_status, list_deployed_models) by @…
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:
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →