NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #121 most downloaded on PyPI
Client library to download and publish models, datasets and other repos on the huggingface.co hub
Latest stable
2.4.0
Last release 24 days ago
29 Oct 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 57 of the last 60 stable releases
8 versions withdrawn
withdrawn after publishing
6 years old
338 releases · first in 2020
Drag across the ruler to compare, or tap a release to open it.
Nothing published for this version
Nothing published for this version
In huggingface_hub v1.0 release, we've removed our dependency on aiohttp to replace it with httpx but we forgot to remove it from the huggingface_hub[
In huggingface_hub v1.0 release, we've removed our dependency on aiohttp to replace it with httpx but we forgot to remove it from the huggingface_hub[inference] extra dependencies in setup.py. This patch release removes it, making the inference extra removed as well.
The internal method _import_aiohttp being unused, it has been removed as well.
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v1.0.0...v1.0.1
Your coding agent can read these notes before it upgrades. Set up the MCP server →
The CLI now also checks for updates in the background, ensuring you never miss important improvements or security fixes. Once every 24 hours, the CLI…
<img width="1497" height="785" alt="Screenshot 2025-10-24 at 10 51 55" src="https://github.com/user-attachments/assets/c54cca25-134c-431f-8819-66e735fbeab5" />
Check out our blog post announcement!
The huggingface_hub library now uses httpx instead of requests for HTTP requests. This change was made to improve performance and to support both synchronous and asynchronous requests the same way. We therefore dropped both requests and aiohttp dependencies.
The get_session and hf_raise_for_status still exist and respectively returns an httpx.Client and processes a httpx.Response object. An additional get_async_client utility has been added for async logic.
The exhaustive list of breaking changes can be found here.
hf_raise_for_status on async stream + tests by @Wauplin in #3442git_vs_http guide by @Wauplin in #3357huggingface_hub 1.0 marks a complete transformation of our command-line experience. We've reimagined the CLI from the ground up, creating a tool that feels native to modern ML workflows while maintaining the simplicity the community love.
huggingface-cliThis release marks the end of an era with the complete removal of the huggingface-cli command. The new hf command (introduced in v0.34.0) takes its place with a cleaner, more intuitive design that follows a logical "resource-action" pattern. This breaking change simplifies the user experience and aligns with modern CLI conventions - no more typing those extra 11 characters!
huggingface-cli entirely in favor of hf by @Wauplin in #3404hf CLI RevampThe new CLI introduces a comprehensive set of commands for repository and file management that expose powerful HfApi functionality directly from the terminal:
> hf repo --help
Usage: hf repo [OPTIONS] COMMAND [ARGS]...
Manage repos on the Hub.
Options:
--help Show this message and exit.
Commands:
branch Manage branches for a repo on the Hub.
create Create a new repo on the Hub.
delete Delete a repo from the Hub.
move Move a repository from a namespace to another namespace.
settings Update the settings of a repository.
tag Manage tags for a repo on the Hub.
A dry run mode has been added to hf download, which lets you preview exactly what will be downloaded before committing to the transfer—showing file sizes, what's already cached, and total bandwidth requirements in a clean table format:
> hf download gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|██████████████████████████████████████████████████████████| 26/26 [00:00<00:00, 50.66it/s]
[dry-run] Will download 26 files (out of 26) totalling 5.6G.
File Bytes to download
--------------------------------- -----------------
.gitattributes 445.0
64-8bits.tflite 125.2M
64-fp16.tflite 248.3M
64.tflite 495.8M
README.md 8.1K
config.json 665.0
flax_model.msgpack 497.8M
generation_config.json 124.0
merges.txt 456.3K
model.safetensors 548.1M
onnx/config.json 879.0
onnx/decoder_model.onnx 653.7M
onnx/decoder_model_merged.onnx 655.2M
...
The CLI now provides intelligent shell auto-completion that suggests available commands, subcommands, options, and arguments as you type - making command discovery effortless and reducing the need to constantly check --help.
The CLI now also checks for updates in the background, ensuring you never miss important improvements or security fixes. Once every 24 hours, the CLI silently checks PyPI for newer versions and notifies you when an update is available - with personalized upgrade instructions based on your installation method.
The cache management CLI has been completely revamped with the removal of hf scan cache and hf scan delete in favor of docker-inspired commands that are more intuitive. The new hf cache ls provides rich filtering capabilities, hf cache rm enables targeted deletion, and hf cache prune cleans up detached revisions.
# List cached repos
>>> hf cache ls
ID SIZE LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script
model/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main
model/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main
Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk.
# List cached repos with filters
>>> hf cache ls --filter "type=model" --filter "size>3G" --filter "accessed>7d"
# Output in different format
>>> hf cache ls --format json
>>> hf cache ls --revisions # Replaces the old --verbose flag
# Cache removal
>>> hf cache rm model/meta-llama/Llama-2-70b-hf
>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) # Remove old items
# Clean up detached revisions
hf cache prune # Removes all unreferenced revisions
Under the hood, this transformation is powered by Typer, significantly reducing boilerplate and making the CLI easier to maintain and extend with new features.
hf cache by @hanouticelina in #3439The new cross-platform installers simplify CLI installation by creating isolated sandboxed environments without interfering with your existing Python setup or project dependencies. The installers work seamlessly across macOS, Linux, and Windows, automatically handling dependencies and PATH configuration.
# On macOS and Linux
>>> curl -LsSf https://hf.co/cli/install.sh | sh
# On Windows
>>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
Finally, the [cli] extra has been removed - The CLI now ships with the core huggingface_hub package.
[cli] extra by @hanouticelina in #3451The v1.0 release is a major milestone for the huggingface_hub library. It marks our commitment to API stability and the maturity of the library. We have made several improvements and breaking changes to make the library more robust and easier to use. A migration guide has been written to reduce friction as much as possible: https://huggingface.co/docs/huggingface_hub/concepts/migration.
We'll list all breaking changes below:
Minimum Python version is now 3.9 (instead of 3.8).
HTTP backend migrated from requests to httpx. Expect some breaking changes on advances features and errors. The exhaustive list can be found here.
The deprecated huggingface-cli has been removed, hf (introduced in v0.34) replaces it with a clearer ressource-action CLI.
huggingface-cli entirely in favor of hf by @Wauplin in #3404The [cli] extra has been removed - The CLI now ships with the core huggingface_hub package.
[cli] extra by @hanouticelina in #3451Long deprecated classes like HfFolder, InferenceAPI, and Repository have been removed.
HfFolder and InferenceAPI classes by @Wauplin in #3344Repository class by @Wauplin in #3346constant.hf_cache_home have been removed. Use constants.HF_HOME instead.
use_auth_token is not supported anymore. Use token instead. Previously using use_auth_token automatically redirected to token with a warning
removed get_token_permission. Became useless when fine-grained tokens arrived.
removed update_repo_visibility. Use update_repo_settings instead.
removed is_write_action is all build_hf_headers methods. Not relevant since fine-grained tokens arrived.
removed write_permission arg from login method. Not relevant anymore.
renamed login(new_session) to login(skip_if_logged_in) in login methods. Not announced but hopefully very little friction. Only some notebooks to update on the Hub (will do it once released)
removed resume_download / force_filename / local_dir_use_symlinks parameters from hf_hub_download/snapshot_download (and mixins)
removed library / language / tags / task from list_models args
upload_file/upload_folder now returns a url to the commit created on the Hub as any other method creating a commit (create_commit, delete_file, etc.)
require keyword arguments on login methods
Remove any Keras 2.x and tensorflow-related code
hf_transfer support. hf_xet is now the default upload/download manager
Routing for Chat Completion API in Inference Providers is now done server-side. This saves 1 HTTP call + allows us to centralize logic to route requests to the correct provider. In the future, it enables use cases like choosing fastest or cheapest provider directly.
Also some updates in the docs:
We've added support for TypedDict to our @strict framework, which is our data validation tool for dataclasses. Typed dicts are now converted to dataclasses on-the-fly for validation, without mutating the input data. This logic is currently used by transformers to validate config files but is library-agnostic and can therefore be used by anyone. More details in this guide.
from typing import Annotated, TypedDict
from huggingface_hub.dataclasses import validate_typed_dict
def positive_int(value: int):
if not value >= 0:
raise ValueError(f"Value must be positive, got {value}")
class User(TypedDict):
name: str
age: Annotated[int, positive_int]
# Valid data
validate_typed_dict(User, {"name": "John", "age": 30})
Added a HfApi.list_organization_followers endpoint to list followers of an organization, similar to the existing one for user's followers.
sentence_similarity docstring by @tolgaakar in #3374image-to-image by @hanouticelina in #3399ty 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
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
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
One column per quarter.