●Change8

Migrating to HuggingFace Hub v1.0.0

Version v1.0.0 introduces 3 breaking changes. This guide details how to update your code.

Released: 10/24/2025

3
Breaking Changes
5
Migration Steps
8
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

`huggingface-cli` (removed)`requests` (dependency dropped)`aiohttp` (dependency dropped)`get_session` (now returns `httpx.Client`)`hf_raise_for_status` (now processes `httpx.Response`)`get_async_client` (new utility)`hf scan cache` (removed)`hf scan delete` (removed)

Breaking Changes

●Issue #1

The `huggingface-cli` command has been completely removed and replaced by the `hf` command.

●Issue #2

The `requests` and `aiohttp` dependencies have been dropped due to the migration to `httpx` for HTTP requests.

●Issue #3

The `[cli]` extra for installation has been removed; the CLI is now included with the core `huggingface_hub` package.

Migration Steps

  1. 1
    Replace all invocations of `huggingface-cli` with the new `hf` command.
  2. 2
    If you were relying on `requests` or `aiohttp` directly via internal library functions, update your code to use the returned `httpx.Client` or `httpx.Response` objects.
  3. 3
    If you used cache scanning commands, migrate from `hf scan cache`/`hf scan delete` to `hf cache ls`, `hf cache rm`, or `hf cache prune`.
  4. 4
    If you installed the CLI via the `[cli]` extra, you no longer need it; install the core package.
  5. 5
    Use the provided cross-platform installers for setting up the standalone CLI environment if desired.

Release Summary

Hugging Face Hub library v1.0 introduces a major migration to use httpx for HTTP requests, dropping requests/aiohttp dependencies, and completely revamps the CLI experience, replacing `huggingface-cli` with the new `hf` command.

Need More Details?

View the full release notes and all changes for HuggingFace Hub v1.0.0.

View Full Changelog