huggingface_hub v1.0: A Comprehensive Overview of the Next Generation of Open Machine Learning

huggingface_hub v1.0: A Comprehensive Overview of the Next Generation of Open Machine Learning

huggingface_hub v1.0 marks a significant milestone for the Hugging Face Hub, representing five years of development and a commitment to building the foundation for the future of open machine learning. This release introduces substantial architectural changes, performance improvements, and new features, solidifying the library’s role as the central platform for accessing and sharing machine learning models, datasets, and Spaces. The transition to version 1.0 signifies a strategic shift towards a more robust, scalable, and modern infrastructure.

Executive Summary

After five years of development, huggingface_hub has reached version 1.0. This release is a pivotal moment, marking the library’s maturity as the core infrastructure powering 200,000 dependent libraries, providing access to over 2 million public models, 500k+ public datasets, and 1 million public Spaces. The upgrade introduces breaking changes, primarily focusing on adopting httpx as the backend library and hf_xet for file transfers, while maintaining backward compatibility for most users. The release also includes enhancements to the command-line interface (CLI), the Agents ecosystem, and the overall architecture.

The Evolution of huggingface_hub

The Foundation Years (2020-2021)

• Version 0.0.8: Introduced initial APIs, wrapping Git commands for repository interaction.
• Version 0.0.17: Implemented token-based authentication for secure access to private repositories and uploads.

The Great Shift: Git to HTTP (2022)

• June 2022 (Version 0.8.1): Introduced the HTTP Commit API, enabling direct file uploads via HTTP requests, simplifying workflows, particularly for large model files.
• Introduced a git-aware cache file layout for improved efficiency and deduplication across libraries.

Expanding API Surface (2022–2024)

• Repository Primitives: Mature APIs for listing trees, browsing refs and commits, reading files, syncing folders, managing tags, branches, and release cycles.
• Spaces Integration: Full programmatic control for deploying and managing interactive ML demos.
• Inference Endpoints: Integration for deploying models on production-scale infrastructure (Q3 2025).
• Social and Community Features: APIs for pull requests, comments, user/organization info, likes, following/followers, and Collections.
• Improved Ergonomics: Seamless authentication in Colab, resumable downloads, reliable uploads of large folders.
• Inference Providers Ecosystem (Version 0.28.0): Introduced a unified API for accessing models from multiple serverless providers (Together AI, SambaNova, Replicate, Cerebras, Groq, and more) with a pay-per-request architecture.

Ready. Xet. Go! (2024-2025)

• Version 0.30.0: Introduced Xet, a new protocol for storing large objects in Git repositories, operating at the chunk level (64KB chunks) for faster and smarter uploads/downloads.
• Migration to Xet: A transparent migration process, with 77PB+ across 6,000,000 repositories migrated to the Xet backend.

Key Architectural Changes

Migration to httpx

• Replaced the requests library with httpx for improved performance, HTTP/2 support, and thread safety.
• Provides a unified API for both synchronous and asynchronous operations.
• Migration is designed to be largely transparent; users with custom backends will need to update their configurations.

Adoption of hf_xet

• hf_xet is now the default backend for uploading and downloading files, replacing the legacy hf_transfer.
• Xet operates at the chunk level (64KB chunks), enabling efficient updates and downloads.
• The migration to Xet has been fully transparent, with no user intervention required.

Modernized CLI

• The huggingface-cli has been replaced with a streamlined hf CLI.
• Provides a comprehensive interface for authentication (hf auth login), file transfers (hf upload, hf download), repository management (hf repo), cache management (hf cache ls, hf cache rm), and compute (hf jobs run).
• The CLI is now packaged with a sandboxed installer for easy upgrades.

Deprecations and Cleanup

• The old Repository class and HfApi class have been removed.
• upload_file() and create_commit() methods are now handled through the more efficient hf_xet.
• The HfFolder class has been replaced with explicit login(), logout(), and get_token() functions.
• The huggingface_hub v0.x versions will no longer receive new features, but will remain available for backward compatibility.

Growth and Impact

• 113.5 million monthly downloads (October 2025).
• Powers access to 2M+ public models, 500k+ public datasets, and 1M+ public Spaces.
• Used by 60k+ users daily and 550k+ monthly.
• Trusted by 200k+ companies.
• 200,000+ repositories on GitHub and 3,000 packages on PyPI depend on huggingface_hub.

Building for the Next Decade

Agents Ecosystem

• Introduced the Model Context Protocol (MCP) for standardized interaction with tools.
• tiny-agents CLI simplifies the creation and deployment of AI agents.
• Leverages the existing InferenceClient and its supported providers.

Migration and Compatibility

• The migration to v1.0 has been carefully planned to maintain backward compatibility.
• Most libraries should work seamlessly with both v0.x and v1.x versions.
• The main exception is the transformers library, which requires v0.x in its v4 releases and v1.x in its upcoming v5 release.
• A detailed compatibility overview is available in the issue linked in the release notes.

Acknowledgments

• The release is a testament to the contributions of 280+ contributors.
• Gratitude is extended to the Hugging Face community for feedback, bug reports, and suggestions.
• The project acknowledges the support of its users, from individual developers to large enterprises.

Conclusion

huggingface_hub v1.0 represents a significant step forward in the evolution of open machine learning. The release introduces crucial improvements in performance, scalability, and developer experience, positioning the library to meet the growing demands of the ML community. The commitment to backward compatibility and a transparent migration process ensures a smooth transition for users, while the focus on future-proof architecture paves the way for continued innovation.