[v1.2.3] Fix `private` default value in CLI

Patch release for #3618 by @Wauplin.

When creating a new repo, we should default to private=None instead of private=False. This is already the case when using the API but not when using the CLI. This is a bug likely introduced when switching to Typer. When defaulting to None, the repo visibility will default to False except if the organization has configured repos to be "private by default" (the check happens server-side, so it shouldn't be hardcoded client-side).

Full Changelog: v1.2.2...v1.2.3

[v1.2.2] Fix unbound local error in local folder metadata + fix `hf auth list` logs

• Fix unbound local error when reading corrupted metadata files by @Wauplin in #3610
• Fix auth_list not showing HF_TOKEN message when no stored tokens exist by @hanouticelina in #3608

Full Changelog: v1.2.1...v1.2.2

v1.2.1: Smarter Rate Limit Handling, Daily Papers API and more QoL improvements!

🚦 Smarter Rate Limit Handling

We've improved how the huggingface_hub library handles rate limits from the Hub. When you hit a rate limit, you'll now see clear, actionable error messages telling you exactly how long to wait and how many requests you have left.

HfHubHTTPError: 429 Too Many Requests for url: https://huggingface.co/api/models/username/reponame.
Retry after 55 seconds (0/2500 requests remaining in current 300s window).

When a 429 error occurs, the SDK automatically parses the RateLimit header to extract the exact number of seconds until the rate limit resets, then waits precisely that duration before retrying. This applies to file downloads (i.e. Resolvers), uploads, and paginated Hub API calls (list_models, list_datasets, list_spaces, etc.).

More info about Hub rate limits in the docs 👉 here.

• Parse rate limit headers for better 429 error messages by @hanouticelina in #3570
• Use rate limit headers for smarter retry in http backoff by @hanouticelina in #3577
• Harmonize retry behavior for metadata fetch and HfFileSystem by @hanouticelina in #3583
• Add retry for preupload endpoint by @hanouticelina in #3588
• Use default retry values in pagination by @hanouticelina in #3587

✨ HF API

Daily Papers endpoint: You can now programmatically access Hugging Face's daily papers feed. You can filter by week, month, or submitter, and sort by publication date or trending.

from huggingface_hub import list_daily_papers

for paper in list_daily_papers(date="2025-12-03"):
    print(paper.title)

# DeepSeek-V3.2: Pushing the Frontier of Open Large Language Models
# ToolOrchestra: Elevating Intelligence via Efficient Model and Tool Orchestration
# MultiShotMaster: A Controllable Multi-Shot Video Generation Framework
# Deep Research: A Systematic Survey
# MG-Nav: Dual-Scale Visual Navigation via Sparse Spatial Memory
...

Add daily papers endpoint by @BastienGimbert in #3502
Add more parameters to daily papers by @Samoed in #3585

Offline mode helper: we recommend using huggingface_hub.is_offline_mode() to check whether offline mode is enabled instead of checking HF_HUB_OFFLINE directly.

Add offline_mode helper by @Wauplin in #3593
Rename utility to is_offline_mode by @Wauplin #3598

Inference Endpoints: You can now configure scaling metrics and thresholds when deploying endpoints.

feat(endpoints): scaling metric and threshold by @oOraph in #3525

Exposed utilities: RepoFile and RepoFolder are now available at the root level for easier imports.

Expose RepoFile and RepoFolder at root level by @Wauplin in #3564

⚡️ Inference Providers

OVHcloud AI Endpoints was added as an official Inference Provider in v1.1.5. OVHcloud provides European-hosted, GDPR-compliant model serving for your AI applications.

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    api_key=os.environ["HF_TOKEN"],
)

completion = client.chat.completions.create(
    model="openai/gpt-oss-20b:ovhcloud",
    messages=[
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
)

print(completion.choices[0].message)

Add OVHcloud AI Endpoints as an Inference Provider by @eliasto in #3541

We also added support for automatic speech recognition (ASR) with Replicate, so you can now transcribe audio files easily.

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    provider="replicate",
    api_key=os.environ["HF_TOKEN"],
)

output = client.automatic_speech_recognition("sample1.flac", model="openai/whisper-large-v3")

[Inference Providers] Add support for ASR with Replicate by @hanouticelina in #3538

The truncation_direction parameter in InferenceClient.feature_extraction ( (and its async counterpart) now uses lowercase values ("left"/"right" instead of "Left"/"Right") for consistency with other specs. The Async counterpart has been updated as well

[Inference] Use lowercase left/right truncation direction parameter by @Wauplin in #3548

📁 HfFileSystem

HfFileSystem: A new top-level hffs alias make working with the filesystem interface more convenient.

>>> from huggingface_hub import hffs
>>> with hffs.open("datasets/fka/awesome-chatgpt-prompts/prompts.csv", "r") as f:
...     print(f.readline())
"act","prompt"
"An Ethereum Developer","Imagine you are an experienced Ethereum developer tasked..."

[HfFileSystem] Add top level hffs by @lhoestq in #3556
[HfFileSystem] Add expand_info arg by @lhoestq in #3575

💔 Breaking Change

Paginated results when listing user access requests: list_pending_access_requests, list_accepted_access_requests, and list_rejected_access_requests now return an iterator instead of a list. This allows lazy loading of results for repositories with a large number of access requests. If you need a list, wrap the call with list(...).

Paginated results in list_user_access by @Wauplin in #3535

🔧 Other QoL Improvements

• Better default for num_workers by @Qubitium in #3532
• Avoid redundant call to the Xet connection info URL by @Wauplin in #3534
• Pass through additional arguments from HfApi download utils by @schmrlng in #3531
• Add optional cache to whoami by @Wauplin in #3568
• Enhance repo_type_and_id_from_hf_id by @pulltheflower in #3507
• Warn on server warning 'X-HF-Warning' by @Wauplin in #3589
• Just print server warning without hardcoded client-side addition by @Wauplin in #3592
• Decrease number of files before falling back to list_repo_tree in snapshot_download by @hanouticelina in #3565

📖 Documentation

• [Docs] Update CLI installation guide by @hanouticelina in #3536
• Fix: correct hf login example to hf auth login by @alisheryeginbay in #3590

🛠️ Small fixes and maintenance

🐛 Bug and typo fixes

• [Inference] Fix zero shot classification output parsing by @hanouticelina in #3561
• Fix FileNotFoundError in CLI update check by @hanouticelina in #3574
• Fix HfHubHTTPError reduce error by adding factory function by @owenowenisme in #3579
• Make 'name' optional in catalog deploy by @Wauplin in #3529
• Do not use rich in tiny-agents CLI by @Wauplin in #3573
• use constants.HF_HUB_ETAG_TIMEOUT as timeout for get_hf_file_metadata by @krrome in #3595

🏗️ Internal

• Add huggingface_hub as dependency for hf by @Wauplin in #3527
• Prepare for 1.2 release by @hanouticelina in #3528
• [Internal] Fix CI by @hanouticelina in #3544
• Fix test_list_spaces_linked in CI by @Wauplin in #3549
• Fix minor things in CI by @Wauplin in #3558
• [Internal] Fix quality by @hanouticelina in #3572
• Fix quality by @hanouticelina in #3584

Significant community contributions

The following contributors have made significant changes to the library over the last release:

• @schmrlng
  • Pass through additional arguments from HfApi download utils (#3531)
• @eliasto
  • Add OVHcloud AI Endpoints as an Inference Provder (#3541)
• @Boulaouaney
  • Add uv support to installation scripts for faster package installation (#3486)
• @pulltheflower
  • Enhance repo_type_and_id_from_hf_id of hf_api (#3507)
• @owenowenisme
  • Fix HfHubHTTPError reduce error by adding factory function (#3579)
• @BastienGimbert
  • Add daily papers endpoint (#3502)
• @Samoed
  • Add more parameters to daily papers (#3585)

[v1.1.7] Make `hffs` accessible at root-level

[HfFileSystem] Add top level hffs by @lhoestq #3556.

Example:

>>> from huggingface_hub import hffs
>>> with hffs.open("datasets/fka/awesome-chatgpt-prompts/prompts.csv", "r") as f:
...     print(f.readline())
...     print(f.readline())
"act","prompt"
"An Ethereum Developer","Imagine you are an experienced Ethereum developer tasked..."

Full Changelog: v1.1.6...v1.1.7

[v1.1.6] Fix incomplete file listing in `snapshot_download` + other bugfixes

This release includes multiple bug fixes:

• decrease number of files before falling back to list_repo_tree in snapshot_download #3565 by @hanouticelina
• Fix HfHubHTTPError reduce error by adding factory function #3579 by @owenowenisme
• Fix FileNotFoundError in CLI update check #3574 by @hanouticelina
• Do not use rich in tiny-agents CLI #3573 by @Wauplin

---

Full Changelog: v1.1.5...v1.1.6

[v1.1.5] Welcoming OVHcloud AI Endpoints as a new Inference Provider & More

⚡️ New Inference Provider: OVHcloud AI Endpoints

OVHcloud AI Endpoints is now an official Inference Provider on Hugging Face! 🎉
OVHcloud delivers fast, production ready inference on secure, sovereign, fully 🇪🇺 European infrastructure - combining advanced features with competitive pricing.

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    api_key=os.environ["HF_TOKEN"],
)

completion = client.chat.completions.create(
    model="openai/gpt-oss-20b:ovhcloud",
    messages=[
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
)

print(completion.choices[0].message)

More snippets examples in the provider documentation 👉 here.

• Add OVHcloud AI Endpoints as an Inference Provder in #3541 by @eliasto

QoL Improvements

Installing the CLI is now much faster, thanks to @Boulaouaney for adding support for uv, bringing faster package installation.

• Add uv support to installation scripts for faster package installation in #3486 by @Boulaouaney

Bug Fixes

This release also includes the following bug fixes:

• [Collections] Add collections to collections by slug id in #3551 by @hanouticelina
• [CLI] Respect HF_DEBUG environment variable in #3562 by @hanouticelina
• [Inference] fix zero shot classification output parsing in #3561 by @hanouticelina

[v1.1.4] Paginated results in list_user_access

• Paginated results in list_user_access by @Wauplin in #3535
  ⚠️ This patch release is a breaking chance but necessary to reflect API update made server-side.

Full Changelog: v1.1.3...v1.1.4

[v1.1.3] Avoid HTTP 429 on downloads + fix missing arguments in download API

• Make 'name' optional in catalog deploy by @Wauplin in #3529
• Pass through additional arguments from HfApi download utils by @schmrlng in #3531
• Avoid redundant call to the Xet connection info URL by @Wauplin in #3534
  • => this PR fixes HTTP 429 rate limit issues happening when downloading a very large dataset of small files

Full Changelog: v1.1.0...v1.1.3

v1.1.0: Faster Downloads, new CLI features and more!

🚀 Optimized Download Experience

⚡ This release significantly improves the file download experience by making it faster and cleaning up the terminal output.

snapshot_download is now always multi-threaded, leading to significant performance gains. We removed a previous limitation, as Xet's internal resource management ensures we can parallelize downloads safely without resource contention. A sample benchmark showed this made the download much faster!

Additionally, the output for snapshot_download and hf download CLI is now much less verbose. Per file logs are hidden by default, and all individual progress bars are combined into a single progress bar, resulting in a much cleaner output.

• Multi-threaded snapshot download by @Wauplin in #3522
• Compact output in snapshot_download and hf download by @Wauplin in #3523

Inference Providers

🆕 WaveSpeedAI is now an official Inference Provider on Hugging Face! 🎉 WaveSpeedAI provides fast, scalable, and cost-effective model serving for creative AI applications, supporting text-to-image, image-to-image, text-to-video, and image-to-video tasks. 🎨

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    provider="wavespeed",
    api_key=os.environ["HF_TOKEN"],
)

video = client.text_to_video(
    "A cat riding a bike",
    model="Wan-AI/Wan2.2-TI2V-5B",
)

More snippets examples in the provider documentation 👉 here.

We also added support for image-segmentation task for fal, enabling state-of-the-art background removal with RMBG v2.0.

import os
from huggingface_hub import InferenceClient

client = InferenceClient(
    provider="fal-ai",
    api_key=os.environ["HF_TOKEN"],
)

output = client.image_segmentation("cats.jpg", model="briaai/RMBG-2.0")

• [inference provider] Add wavespeed.ai as an inference provider by @arabot777 in #3474
• [Inference Providers] implement image-segmentation for fal by @hanouticelina in #3521

🦾 CLI continues to get even better!

Following the complete revamp of the Hugging Face CLI in v1.0, this release builds on that foundation by adding powerful new features and improving accessibility.

New hf PyPI Package

To make the CLI even easier to access, we've published a new, minimal PyPI package: hf. This package installs the hf CLI tool and It's perfect for quick, isolated execution with modern tools like uvx.

# Run the CLI without installing it
> uvx hf auth whoami

⚠️ Note: This package is for the CLI only. Attempting to import hf in a Python script will correctly raise an ImportError.

A big thank you to @thorwhalen for generously transferring the hf package name to us on PyPI. This will make the CLI much more accessible for all Hugging Face users. 🤗

• Upload hf CLI to PyPI by @Wauplin in #3511

Manage Inference Endpoints

A new command group, hf endpoints, has been added to deploy and manage your Inference Endpoints directly from the terminal.

This provides "one-liners" for deploying, deleting, updating, and monitoring endpoints. The CLI offers two clear paths for deployment: hf endpoints deploy for standard Hub models and hf endpoints catalog deploy for optimized Model Catalog configurations.

> hf endpoints --help
Usage: hf endpoints [OPTIONS] COMMAND [ARGS]...

  Manage Hugging Face Inference Endpoints.

Options:
  --help  Show this message and exit.

Commands:
  catalog        Interact with the Inference Endpoints catalog.
  delete         Delete an Inference Endpoint permanently.
  deploy         Deploy an Inference Endpoint from a Hub repository.
  describe       Get information about an existing endpoint.
  ls             Lists all Inference Endpoints for the given namespace.
  pause          Pause an Inference Endpoint.
  resume         Resume an Inference Endpoint.
  scale-to-zero  Scale an Inference Endpoint to zero.
  update         Update an existing endpoint.

• [CLI] Add Inference Endpoints Commands by @hanouticelina in #3428

Verify Cache Integrity

A new command, hf cache verify, has been added to check your cached files against their checksums on the Hub. This is a great tool to ensure your local cache is not corrupted and is in sync with the remote repository.

> hf cache verify --help
Usage: hf cache verify [OPTIONS] REPO_ID

  Verify checksums for a single repo revision from cache or a local directory.

  Examples:
  - Verify main revision in cache: `hf cache verify gpt2`
  - Verify specific revision: `hf cache verify gpt2 --revision refs/pr/1`
  - Verify dataset: `hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset`
  - Verify local dir: `hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo`

Arguments:
  REPO_ID  The ID of the repo (e.g. `username/repo-name`).  [required]

Options:
  --repo-type [model|dataset|space]
                                  The type of repository (model, dataset, or
                                  space).  [default: model]
  --revision TEXT                 Git revision id which can be a branch name,
                                  a tag, or a commit hash.
  --cache-dir TEXT                Cache directory to use when verifying files
                                  from cache (defaults to Hugging Face cache).
  --local-dir TEXT                If set, verify files under this directory
                                  instead of the cache.
  --fail-on-missing-files         Fail if some files exist on the remote but
                                  are missing locally.
  --fail-on-extra-files           Fail if some files exist locally but are not
                                  present on the remote revision.
  --token TEXT                    A User Access Token generated from
                                  https://huggingface.co/settings/tokens.
  --help                          Show this message and exit.

• [CLI] Add hf cache verify by @hanouticelina in #3461

Cache Sorting and Limiting

Managing your local cache is now easier. The hf cache ls command has been enhanced with two new options:

• --sort: Sort your cache by accessed, modified, name, or size. You can also specify order (e.g., modified:asc to find the oldest files).
• --limit: Get just the top N results after sorting (e.g., --limit 10).

# List top 10 most recently accessed repos
> hf cache ls --sort accessed --limit 10

# Find the 5 largest repos you haven't used in over a year
> hf cache ls --filter "accessed>1y" --sort size --limit 5

• Add sort and limit parameters in hf cache ls by @Wauplin in #3510

Finally, we've patched the CLI installer script to fix a bug for zsh users. The installer now works correctly across all common shells.

• Use hf installer with bash by @Wauplin in #3498
• make installer work for zsh by @hanouticelina in #3513

🔧 Other

We've fixed a bug in HfFileSystem where the instance cache would break when using multiprocessing with the "fork" start method.

• [HfFileSystem] improve cache for multiprocessing fork and multithreading by @lhoestq in #3500

🌍 Documentation

Thanks to @BastienGimbert for translating the README to French 🇫🇷 🤗

• i18n: add French README translation by @BastienGimbert in #3490

and Thanks to @didier-durand for fixing multiple language typos in the library! 🤗

• [Doc]: fix various typos in different files by @didier-durand in #3499
• [Doc]: fix various typos in different files by @didier-durand in #3509
• [Doc]: fix various typos in different files by @didier-durand in #3514
• [Doc]: fix various typos in different files by @didier-durand in #3517
• [Doc]: fix various typos in different files by @didier-durand in #3497

🛠️ Small fixes and maintenance

🐛 Bug and typo fixes

• Close HTTP sessions on fork by @Wauplin in #3508
• Fix some outdated docs by @Wauplin in #3495

🏗️ internal

• Remove aiohttp dependency by @Wauplin in #3488
• Prepare for 1.1.0 by @Wauplin in #3489
• Fix type annotations in inference codegen by @Wauplin in #3496
• Add CI + official support for Python 3.14 by @Wauplin in #3483
• [Internal] Fix quality issue generated from update-inference-types workflow by @hanouticelina in #3516

Significant community contributions

The following contributors have made significant changes to the library over the last release:

• @arabot777
  • [inference provider] Add wavespeed.ai as an inference provider (#3474)
• @BastienGimbert
  • i18n: add French README translation (#3490)
• @didier-durand
  • [Doc]: fix various typos in different files (#3497)
  • [Doc]: fix various typos in different files (#3499)
  • [Doc]: fix various typos in different files (#3509)
  • [Doc]: fix various typos in different files (#3514)
  • [Doc]: fix various typos in different files (#3517)

[v1.0.1] Remove `aiohttp` from extra dependencies

In huggingface_hub v1.0 release, we've removed our dependency on aiohttp to replace it with httpx but we forgot to remove it from the huggingface_hub[inference] extra dependencies in setup.py. This patch release removes it, making the inference extra removed as well.

The internal method _import_aiohttp being unused, it has been removed as well.

• Remove aiohttp dependency by @Wauplin in #3488

Full Changelog: v1.0.0...v1.0.1