v0.25.0: Large uploads made simple + quality of life improvements
Uploading large models or datasets is challenging. We've already written some tips and tricks to facilitate the process but something was still missing. We are now glad to release the huggingface-cli upload-large-folder command. Consider it as a "please upload this no matter what, and be quick" command. Contrarily to huggingface-cli download, this new command is more opinionated and will split the upload into several commits. Multiple workers are started locally to hash, pre-upload and commit the files in a way that is resumable, resilient to connection errors, and optimized against rate limits. This feature has already been stress tested by the community over the last months to make it as easy and convenient to use as possible.
Here is how to use it:
huggingface-cli upload-large-folder <repo-id> <local-path> --repo-type=datasetEvery minute, a report is logged with the current status of the files and workers:
---------- 2024-04-26 16:24:25 (0:00:00) ----------
Files: hashed 104/104 (22.5G/22.5G) | pre-uploaded: 0/42 (0.0/22.5G) | committed: 58/104 (24.9M/22.5G) | ignored: 0
Workers: hashing: 0 | get upload mode: 0 | pre-uploading: 6 | committing: 0 | waiting: 0
---------------------------------------------------You can also run it from a script:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_large_folder(
... repo_id="HuggingFaceM4/Docmatix",
... repo_type="dataset",
... folder_path="/path/to/local/docmatix",
... )
For more details about the command options, run:
huggingface-cli upload-large-folder --helpor visit the upload guide.
The search API have been updated. You can now list gated models and datasets, and filter models by their inference status (warm, cold, frozen).
More complete support for the expand[] parameter:
Organizations are now included when retrieving the user overview:
get_user_overview by @Wauplin in #2404get_user_followers and get_user_following are now paginated. This was not the case before, leading to issues for users with more than 1000 followers.
Added auth_check to easily verify if a user has access to a repo. It raises GatedRepoError if the repo is gated and the user don't have the permission or RepositoryNotFoundError if the repo does not exist or is private. If the method does not raise an error, you can assume the user has the permission to access the repo.
>>> from huggingface_hub import auth_check
>>> from huggingface_hub.utils import GatedRepoError, RepositoryNotFoundError
try:
auth_check("user/my-cool-model")
except GatedRepoError:
# Handle gated repository error
print("You do not have permission to access this gated repository.")
except RepositoryNotFoundError:
# Handle repository not found error
print("The repository was not found or you do not have access.")
auth_check by @cjfghk5697 in #2497It is now possible to set a repo as gated from a script:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.update_repo_settings(repo_id=repo_id, gated="auto") # Set to "auto", "manual" or False
update_repo_settings function to HfApi #2447 by @WizKnight in #2502A few improvements in the InferenceEndpoint API. It's now possible to set a scale_to_zero_timeout parameter + to configure secrets when creating or updating an Inference Endpoint.
The torch serialization module now supports tensor subclasses.
We also made sure that now the library is tested with both torch 1.x and 2.x to ensure compatibility.
weights_only=True by @Wauplin in #2488Breaking changes:
InferenceClient.conversational task has been removed in favor of InferenceClient.chat_completion. Also removed ConversationalOutput data class.InferenceClient output values are now dataclasses, not dictionaries.list_repo_likers is now paginated. This means the output is now an iterator instead of a list.Deprecation:
multi_commit: bool parameter in upload_folder is not deprecated, along the create_commits_on_pr. It is now recommended to use upload_large_folder instead. Thought its API and internals are different, the goal is still to be able to upload many files in several commits.Thanks to community feedback, we've been able to improve or fix significant things in both the InferenceClient and its async version AsyncInferenceClient. This fixes have been mainly focused on the OpenAI-compatible chat_completion method and the Inference Endpoints services.
stop parameter in text-generation instead of stop_sequences by @Wauplin in #2473InferenceClient for HF Nvidia NIM API by @Wauplin in #2482AsyncInferenceClient by @Wauplin in #2496When uploading a folder, we validate the README.md file before hashing all the files, not after. This should save some precious time when uploading large files and a corrupted model card.
Also, it is now possible to pass a --max-workers argument when uploading a folder from the CLI
All custom exceptions raised by huggingface_hub are now defined in huggingface_hub.errors module. This should make it easier to import them for your try/except statements.
At the same occasion, we've reworked how errors are formatted in hf_raise_for_status to print more relevant information to the users.
All constants in huggingface_hub are now imported as a module. This makes it easier to patch their values, for example in a test pipeline.
constants import to use module-level access #1172 by @WizKnight in #2453Other quality of life improvements:
HFSummaryWriter with 'hf-summary-writer' by @Wauplin in #2398RepoUrl info in CommitInfo object by @Wauplin in #2487touch() if OSError (to cache non existence of file) by @Wauplin in #2505The following contributors have made significant changes to the library over the last release:
auth_check (#2497)constants import to use module-level access #1172 (#2453)update_repo_settings function to HfApi #2447 (#2502)Fetched April 7, 2026