huggingface_hub v1.0: Five Years of Building the Foundation of Open Machine Learning

TL;DR: After five years of development, huggingface_hub has reached v1.0 - a milestone that marks the library's maturity as 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 next decade of open machine learning, driven by a global community of almost 300 contributors and millions of users.

🚀 We highly recommend upgrading to v1.0 to benefit from major performance improvements and new capabilities.

The Story Behind the Library

The library evolved from a simple Git wrapper in 2020 to a mature foundation powering the Hugging Face Hub over five years.

The Foundation Years (2020-2021)

The early releases established the basics: version 0.0.8 introduced first APIs wrapping Git commands, and version 0.0.17 added token-based authentication for private repositories and uploads.

The Great Shift: Git to HTTP (2022)

In June 2022, version 0.8.1 introduced the HTTP Commit API, allowing file uploads via HTTP without Git LFS, and added a git-aware cache layout shared across libraries.

An Expanding API Surface (2022–2024)

As the Hub grew, the library added primitives for repository metadata, webhooks, Spaces management, Inference Endpoints, Jobs API, community features like pull requests and comments, and Inference Providers for pay‑per‑request inference.

Ready. Xet. Go! (2024-2025)

Version 0.30.0 introduced Xet, a chunk‑level storage protocol; the migration moved 77PB+ across over 6,000,000 repositories transparently, enabling faster uploads and downloads.

Measuring Growth and Impact

The library now sees massive adoption, powering millions of models and used by hundreds of thousands of users and companies.

  • 113.5 million monthly downloads, 1.6 billion total (October 2025).
  • Powers access to 2M+ public models, 500k+ public datasets, 1M+ public Spaces (plus private copies).
  • Used by 60k+ daily users, 550k+ monthly users.
  • Trusted by 200k+ companies from startups to Fortune 500.
  • Dependency for over 200,000 GitHub repositories and 3,000 PyPI packages, including major frameworks such as Keras, LangChain, PaddleOCR, ChatTTS, YOLO, Google Generative AI, Moshi, NVIDIA NeMo, and Open Sora.
  • Built by almost 300 contributors.

Building for the Next Decade

Version 1.0 introduces strategic breaking changes to scale the library for the next decade.

Modern HTTP Infrastructure with httpx and hf_xet

The migration to httpx and default hf_xet improves performance, thread safety, and async support.

  • httpx replaces requests, bringing native HTTP/2, true thread safety, and a unified sync/async API.
  • hf_xet is now the default package for file transfers, superseding the optional hf_transfer.
  • Custom HTTP backends can migrate from configure_http_backend() to set_client_factory() and set_async_client_factory().

Agents Made Simple with MCP and Tiny-Agents

MCP integration and tiny-agents let developers build AI agents in ~70 lines of Python.

  • The MCPClient provides a standardized way for agents to interact with tools.
  • The tiny-agents CLI runs agents directly from the Hub, connecting to local or remote MCP servers and using any Gradio Space as a tool.
  • Built on top of the existing InferenceClient and its support for dozens of Inference Providers.

A Fully-Featured CLI for Modern Workflows

The redesigned hf CLI replaces huggingface-cli with a Typer‑based interface covering auth, transfers, repo management, cache, and jobs.

  • hf auth login for authentication.
  • hf download and hf upload for file transfers.
  • hf repo for repository management.
  • hf cache ls and hf cache rm for cache management.
  • hf jobs run for cloud compute.
  • Platform‑agnostic installer:
    # macOS or Linux
curl -LsSf https://hf.co/cli/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

Cleaning House for the Future

Legacy classes and patterns removed to simplify the codebase and focus on forward-looking features.

  • The Git‑based Repository class is gone; HTTP‑based methods like upload_file() and create_commit() are now standard.
  • Token management moved from HfFolder to explicit login(), logout(), and get_token() functions.
  • The old InferenceApi class superseded by the more feature‑complete InferenceClient.
  • hf_transfer fully replaced by hf_xet binary package.
  • Most deprecations were announced months in advance with warnings and migration guidance.

The Migration Guide

A comprehensive migration guide eases upgrading, with backward compatibility maintained for most libraries except transformers v5.

  • The guide provides step‑by‑step instructions for each change and explains why each was necessary.
  • Backward compatibility is preserved where possible; for example, HfHubHttpError inherits from both the old requests and new httpx base HTTPError classes.
  • Previous v0.* versions remain on PyPI for vulnerability updates only, while development focuses on v1.0 and beyond.
  • The main exception is transformers, which requires huggingface_hub v0.x for its v4 releases and v1.x for its upcoming v5 release (see compatibility table in issue #3340).

Acknowledgments

Thanks to contributors, community, and users.

  • Over 280 contributors built the library through code, documentation, translations, and community support.
  • The broader Hugging Face community provided feedback, bug reports, and suggestions.
  • Users ranging from individual developers to large enterprises trust huggingface_hub to power their workflows.

Sources