After five years, huggingface_hub reaches version 1.0: a key piece that consolidates how we share models, datasets and apps in the AI community. If you use Python for ML, this affects you right now — and yes, the upgrade is worth it.

What v1.0 means

This release marks the maturity of a library that already powers hundreds of thousands of projects. huggingface_hub is now the Python package behind access to over 2 million models, 500k datasets and 1 million public Spaces. It’s not just a label: it’s a restructuring designed for the next decade of open machine learning.

Practical recommendation: update with pip install --upgrade huggingface_hub to take advantage of performance improvements and new capabilities.

Key technical changes (concise and clear)

• Migration to httpx as the HTTP client. Why does this matter? httpx brings native HTTP/2 support, better connection reuse across threads, and a unified sync/async API. That reduces surprises between synchronous and asynchronous clients and improves efficiency in production.

• hf CLI replaces the old huggingface-cli. It’s rewritten with Typer and offers a more consistent resource-action pattern: hf auth login, hf download, hf upload, hf repo, hf cache ls, hf jobs run, among others.

• hf_xet as the default backend for file transfers, replacing hf_transfer and consolidating the use of the Xet protocol. Xet deduplicates at the chunk level (64KB), not per-file, which speeds up uploads and downloads of large files.

• Removal of old patterns like the Git-based Repository class and migration to modern HTTP methods such as upload_file() and create_commit().

• New tools for agents: integration of the Model Context Protocol (MCP) and tiny-agents, which let you mount conversational agents with just a few lines of Python on top of InferenceClient and the Inference Providers.

Compatibility and migration

The migration to v1.0 was designed carefully to minimize breakage, but there are points you should review:

• In practice, most libraries work with both v0.x and v1.x, but there’s a notable exception: transformers. The v4 branches of transformers require huggingface_hub v0.x, while the expected transformers v5 will require v1.x. Check the compatibility table in the issue referenced by Hugging Face before upgrading critical environments.

• HTTP backend changes for advanced users: if you had custom integrations with configure_http_backend(), follow the guide to migrate to set_client_factory() and set_async_client_factory().

• Token handling: HfFolder and older token management patterns have been replaced by explicit functions like login(), logout() and get_token().

• Errors and exceptions: HfHubHttpError inherits from both the old (requests) and the new (httpx) error classes to smooth the transition in exception handling.

Practical migration: commands and examples

• Update the package:

pip install --upgrade huggingface_hub

• Install or update the new hf CLI (macOS / Linux):

curl -LsSf https://hf.co/cli/install.sh | sh

• Windows PowerShell:

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

• Quick example using the HTTP Commit API to upload a file without Git LFS:

from huggingface_hub import upload_file
upload_file(path_or_fileobj="model.pt", path_in_repo="model.pt", repo_id="my-repo", token="hf_...")

• If you use agents: with MCP and tiny-agents you can hook a Gradio Space as a tool and run an agent in fewer than 100 lines. That lowers the friction to experiment with conversational agents and tool pipelines.

Impact on the ecosystem

The numbers speak: over 113 million monthly downloads, presence in 200k+ GitHub repositories, and adoption by major frameworks and companies. Hugging Face designed huggingface_hub so it’s not only useful for their own projects but serves as a common layer for Keras, LangChain, NVIDIA NeMo, YOLO and many others.

The introduction of Inference Providers and a pay-per-request architecture make it easier to deploy models with heterogeneous backends (Together AI, Replicate, SambaNova, Groq, etc.). Xet and the migration of petabytes of data show the platform can scale without breaking existing workflows.

Final reflection

Whether you work in production, research or prototyping, huggingface_hub v1.0 is an invitation to modernize your pipelines: better HTTP, smarter transfers, a more robust CLI and building blocks for agents. The breaking changes aren’t arbitrary; they’re technical choices so the platform stays useful as model size and complexity keep growing.

Too lazy to migrate? Start with a staging environment, run your integration tests and verify compatibility with transformers if you use it. In the long run, maintenance and faster transfers will thank you.

Original source

https://huggingface.co/blog/huggingface-hub-v1