TL;DR: After five years of development, huggingface_hub has reached v1.0 – a milestone that marks the library’s maturity because the Python package powering 200,000 dependent libraries and providing core functionality for accessing over 2 million public models, 0.5 million public datasets, and 1 million public Spaces. This release introduces breaking changes designed to support the following decade of open machine learning, driven by a world community of just about 300 contributors and thousands and thousands of users.
🚀 We highly recommend upgrading to v1.0 to learn from major performance improvements and latest capabilities.
pip install --upgrade huggingface_hub
Major changes on this release include the migration to httpx because the backend library, a very redesigned hf CLI (which replaces the deprecated huggingface-cli) featuring a Typer-based interface with a significantly expanded feature set, and full adoption of hf_xet for file transfers, replacing the legacy hf_transfer. Yow will discover the full release notes here.
We’ve worked hard to be certain that
huggingface_hubv1.0.0 stays backward compatible. In practice, most ML libraries should work seamlessly with each v0.x and v1.x versions. The major exception istransformers, which explicitly requireshuggingface_hubv0.x in its v4 releases and v1.x in its upcoming v5 release. For an in depth compatibility overview across libraries, discuss with the table on this issue.
The Story Behind the Library
Every major library has a story. For huggingface_hub, it began with an easy idea: what if sharing machine learning models might be as easy as sharing code on GitHub?
Within the early days of the Hugging Face Hub, researchers and practitioners faced a standard frustration. Training a state-of-the-art model required significant compute resources and expertise. Once trained, these models often lived in isolation, stored on local machines and shared via (broken) Google Drive links. The AI community was duplicating work, wasting resources, and missing opportunities for collaboration.
The Hugging Face Hub emerged as the reply to this challenge. Initially, it was primarily used to share checkpoints compatible with the transformers library. All of the Python code for interacting with the Hub lived inside this library, making it inaccessible for other libraries to reuse.
In late 2020, we shipped huggingface_hub v0.0.1 with an easy mission: extract the inner logic from transformers and create a dedicated library that might unify tips on how to access and share machine learning models and datasets on the Hugging Face Hub. Initially, the library was as straightforward as a Git wrapper for downloading files and managing repositories. Five years and 35+ releases later, huggingface_hub has evolved far beyond its origins.
Let’s trace that journey.
The Foundation Years (2020-2021)
The early releases established the fundamentals. Version 0.0.8 introduced our first APIs, wrapping Git commands to interact with repositories. Version 0.0.17 brought token-based authentication, enabling secure access to non-public repositories and uploads. These were humble beginnings, but they laid the groundwork for every part that followed.
The Great Shift: Git to HTTP (2022)
In June 2022, version 0.8.1 marked a pivotal moment: we introduced the HTTP Commit API. As a substitute of requiring Git and Git LFS installations, users could now upload files directly through HTTP requests. The brand new create_commit() API simplified workflows dramatically, especially for big model files which can be cumbersome to make use of with Git LFS. As well as, a git-aware cache file layout was introduced. All libraries (not only transformers, but third party ones as well) would now share the identical cache, with explicit versioning and file deduplication.
This wasn’t only a technical improvement. It was a philosophical shift. We were now not constructing a Git wrapper for transformers; we were constructing purpose-built infrastructure for machine learning artifacts that would power any library within the ML ecosystem.
An Expanding API Surface (2022–2024)
Because the Hub grew from a model repository right into a full platform, huggingface_hub kept pace with an expanding API surface. Core repository primitives matured: listing trees, browsing refs and commits, reading files or syncing folders, managing tags, branches, and release cycles. Repository metadata and webhooks rounded up the offering so teams could react to changes in real time.
In parallel, Spaces emerged as an easy yet powerful option to host and share interactive ML demos directly on the Hub. Over time, huggingface_hub gained full programmatic control to deploy and manage Spaces (hardware requests, secrets, environment configuration, uploads). To deploy models on production-scale infrastructure, Inference Endpoints were integrated as well. Finally, the Jobs API got here later (Q3 2025) to finish our compute offering.
The social and community layers became first-class residents too: from APIs for pull requests and comments, to user and organization info, repository likes, following and followers, all over Collections to curate and share sets of related resources. On a regular basis ergonomics improved too: seamless authentication in Colab, resumable downloads, reliable uploads of large-scale folders, and more.
Then got here version 0.28.0 and the Inference Providers ecosystem. As a substitute of a single inference backend, we partnered with multiple serverless providers (Together AI, SambaNova, Replicate, Cerebras, Groq, and more) to serve one API with transparent routing. We adopted a pay-per-request inference architecture that matched how people actually desired to work.
Ready. Xet. Go! (2024-2025)
Version 0.30.0 introduced Xet, a groundbreaking latest protocol for storing large objects in Git repositories. Unlike Git LFS, which deduplicates on the file level, Xet operates on the chunk level (64KB chunks). Once you update a big file in a dataset or a model, only the modified chunks are uploaded or downloaded, not the complete file.
The migration was massive, starting with 20 petabytes across over 500,000 repositories. Yet it happened transparently, with full backward compatibility. One 12 months later, all 77PB+ over 6,000,000 repositories have been migrated to the Xet backend, allowing for much faster (and smarter!) uploads and downloads. This happened with no user intervention, and no disruption to existing workflows 🔥
Measuring Growth and Impact
Measuring the expansion and impact of an open-source library is a difficult task. Numbers tell a story of their very own:
- 113.5 million monthly downloads, 1.6 billion total (October 2025).
- Powers access to 2M+ public models, 500k+ public datasets, 1M+ public Spaces, and about twice as much when accounting for personal repos.
- Utilized by 60k+ users every day, 550k+ monthly
- Trusted by 200k+ corporations from startups to Fortune 500
But the true scale becomes clear whenever you take a look at the ecosystem. huggingface_hub is a dependency for over 200,000 repositories on GitHub and 3,000 packages on PyPI, powering every part from major third-party frameworks like Keras, LangChain, PaddleOCR, ChatTTS, YOLO, Google Generative AI, Moshi, NVIDIA NeMo, and Open Sora, to countless smaller libraries and tools across the ML landscape. Our own ecosystem (transformers, diffusers, datasets, sentence-transformers, lighteval, gradio, peft, trl, smolagents, timm, lerobot, etc.) advantages from this foundation as well.
The remarkable part? A lot of the third-party integrations happened organically, and we played no role in them. The Hugging Face Hub empowers the ML community in countless ways, yet we’re continually humbled by how far it has gone and the way widely it’s used.
Constructing for the Next Decade
Version 1.0 is not only about reaching a milestone. It’s about constructing the inspiration for the following decade of open machine learning. The breaking changes we have made aren’t arbitrary; they’re strategic decisions that position huggingface_hub to scale with the explosive growth of AI while maintaining the reliability that thousands and thousands of developers rely on.
Modern HTTP Infrastructure with httpx and hf_xet
Essentially the most significant architectural change in v1.0 is our migration from requests to httpx. This is not only dependency churn. It is a fundamental upgrade that brings the library into the fashionable era of HTTP.
Why httpx? The advantages are substantial: native HTTP/2 support for higher connection efficiency and true thread safety that permits protected connection reuse across multiple threads. Most significantly, httpx provides a unified API for each synchronous and asynchronous operations, eliminating the subtle behavioral differences that existed between our sync and async inference clients.
The migration was designed to be as transparent as possible. Most users won’t need to vary anything. For those with custom HTTP backends, we have provided clear migration paths from configure_http_backend() to set_client_factory() and set_async_client_factory().
Moreover, hf_xet is now the default package for uploading and downloading files to and from the Hub, replacing the previously optional hf_transfer, which has now been fully removed.
Agents Made Easy with MCP and Tiny-Agents
Version 0.32.0 introduced Model Context Protocol (MCP) integration and tiny-agents, fundamentally changing how developers construct AI agents. What once required complex framework integration now takes roughly 70 lines of Python.
The MCPClient provides a standardized way for AI agents to interact with tools, while the tiny-agents CLI permits you to run agents directly from the Hub. Hook up with local or distant MCP servers, use any Gradio Space as a tool, and construct conversational agents that feel natural and responsive.
All of that is built on top of our existing InferenceClient and the handfuls of Inference Providers it supports. We do consider Agents are the long run, and huggingface_hub is there to offer the constructing blocks that enable AI builders to play with them.
A Fully-Featured CLI for Modern Workflows
The CLI has evolved from an easy command-line tool right into a comprehensive interface for ML operations. The streamlined hf command replaces the legacy huggingface-cli with a contemporary resource-action pattern:
hf auth loginfor authenticationhf downloadandhf uploadfor file transfershf repofor repository managementhf cache lsandhf cache rmfor cache managementhf jobs runfor cloud compute
The CLI comes with a sandboxed installer, making it easy to upgrade without breaking existing dev environments:
# On macOS or Linux
curl -LsSf https://hf.co/cli/install.sh | sh
# or on Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
With autocompletion support and an installer that works across platforms, the CLI now feels as polished as any modern developer tool.
Cleansing House for the Future
Version 1.0 removes legacy patterns that were holding us back. The Git-based Repository class is gone. HTTP-based methods like upload_file() and create_commit() are simpler, more reliable, and higher fitted to modern workflows. The HfFolder token management has been replaced with explicit login(), logout(), and get_token() functions. The old InferenceApi class has been superseded by the more feature-complete InferenceClient. hf_transfer has been fully replaced by hf_xet binary package.
These changes weren’t made frivolously. Most deprecations were announced months upfront with clear warnings and migration guidance. The result’s a cleaner, more maintainable codebase that may concentrate on forward-looking features reasonably than supporting deprecated patterns.
The Migration Guide
We understand that breaking changes are disruptive. That is why we have invested heavily in making the migration as smooth as possible. Our comprehensive migration guide provides step-by-step instructions for each change with explanations of why each change was needed.
Most significantly, we have maintained backward compatibility wherever possible. HfHubHttpError, for instance, inherits from each the old requests and latest httpx base HTTPError classes, ensuring that error handling continues to work across versions.
With this release, we’re fully committing to the long run and we’ll focus exclusively on v1.0 and beyond, ensuring we will deliver the performance, features, and tools the community must interact with the Hugging Face Hub. Previous v0.* versions will remain available on PyPI, but they’ll only receive vulnerability updates.
We’ve worked hard to be certain that
huggingface_hubv1.0.0 stays backward compatible. In practice, most ML libraries should work seamlessly with each v0.x and v1.x versions. The major exception istransformers, which explicitly requireshuggingface_hubv0.x in its v4 releases and v1.x in its upcoming v5 release. For an in depth compatibility overview across libraries, discuss with the table on this issue.
Acknowledgments
To our 280+ contributors who built this library through code, documentation, translations, and community support, thanks!
We’re also deeply grateful to the complete Hugging Face community for his or her feedback, bug reports, and suggestions which have shaped this library.
Finally, an enormous thanks to our users -from individual developers to large enterprises- for trusting huggingface_hub to power your workflows. Your support drives us to maintain improving and innovating.
Please star us on GitHub ⭐ to indicate your support and help us proceed constructing the inspiration of open machine learning. It has been five years, however it continues to be only the start!
