NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #89 most downloaded on PyPI
Client library to download and publish models, datasets and other repos on the huggingface.co hub
Last release today
24 Sep 2026
Ships on a steady schedule
a new release about every 2 weeks
Nearly every release is documented
notes for 56 of the last 60 stable releases
7 versions withdrawn
withdrawn after publishing
6 years old
328 releases · first in 2020
One column per quarter.
Nothing published for this version
This is a patch release fixing a breaking backward compatibility issue.
This is a patch release fixing a breaking backward compatibility issue.
Linked PR: https://github.com/huggingface/huggingface_hub/pull/822
⛔ The following methods have now been removed following a deprecation cycle
Version v0.5.0 is the first version which features an API reference. It is still a work in progress with features lacking, some images not rendering, and a documentation reorg coming up, but should already provide significantly simpler access to the huggingface_hub API.
The documentation is visible here.
The list_models and list_datasets methods have been improved in several ways.
These two methods now accept the token keyword to specify your token. Specifying the token will include your private models and datasets in the returned list.
These two methods now accept the cardData boolean argument. If set to True, the modelcard metadata will also be returned when using these two methods.
The list_models method now also accepts an emissions_trehsholds parameter to filter by carbon emissions.
The Keras serialization and upload methods have been worked on to provide better support for models:
push_to_hub_keraslog_dir parameter for TensorBoard logs, which will automatically spawn a TensorBoard instance on the Hub.include_optimizer parameter to push_to_hub_keras() by @merveenoyan in https://github.com/huggingface/huggingface_hub/pull/616test_keras_integration.py by @merveenoyan in https://github.com/huggingface/huggingface_hub/pull/761A contributing guide is now available for the huggingface_hub repository. For any and all information related to contributing to the repository, please check it out!
Read more about it here: CONTRIBUTING.md.
The huggingface_hub GitHub repository has several checks to ensure that the code respects code quality standards. Opt-in pre-commit hooks have been added in order to make it simpler for contributors to leverage them.
Read more about it in the aforementionned CONTRIBUTING guide.
Repositories can now be renamed and transferred programmatically using move_repo.
⛔ The following methods have now been removed following a deprecation cycle
list_repos_objsThe list_repos_objs and the accompanying CLI utility huggingface-cli repo ls-files have been removed.
The same can be done using the model_info and dataset_info methods.
list_repos_objs and huggingface-cli repo ls-files by @julien-c in https://github.com/huggingface/huggingface_hub/pull/702Python 3.6 support is now dropped as end of life. Using Python 3.6 and installing huggingface_hub will result in version v0.4.0 being installed.
⚠️ Items below are now deprecated and will be removed in a future version
post_method is only executed once by @sgugger in https://github.com/huggingface/huggingface_hub/pull/676settings/token to settings/tokens by @ronvoluted in https://github.com/huggingface/huggingface_hub/pull/699hf_api, logging documentation by @LysandreJik in https://github.com/huggingface/huggingface_hub/pull/748Hf.Api.delete_repo by @adrinjalali in https://github.com/huggingface/huggingface_hub/pull/783HF_ENDPOINT. by @Narsil in https://github.com/huggingface/huggingface_hub/pull/819Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.4.0...v0.5.0
Introduce Tag Listing by @muellerzr in https://github.com/huggingface/huggingface_hub/pull/537
This PR introduces the ability to fetch all available tags for models or datasets and returns them as a nested namespace object, for example:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> tags = api.get_model_tags()
>>> print(tags)
Available Attributes:
* benchmark
* language_creators
* languages
* licenses
* multilinguality
* size_categories
* task_categories
* task_ids
>>> print(tags.benchmark)
Available Attributes:
* raft
* superb
* test
With a goal of adding more tab-completion to the library, this PR introduces two objects:
DatasetSearchArgumentsModelSearchArgumentsThese two AttributeDictionary objects contain all the valid information we can extract from a model as tab-complete parameters. We also include the author_or_organization and dataset (or model) _name as well through careful string splitting.
This PR introduces a new way to search the hub: the ModelFilter class.
It is a simple Enum at first to the user, allowing them to specify what they want to search for, such as:
f = ModelFilter(author="microsoft", model_name="wavlm-base-sd", framework="pytorch")
From there, they can pass in this filter to the new list_models_by_filter function in HfApi to search through it:
models = api.list_modes(filter=f)
The API may then be used for complex queries:
args = ModelSearchArguments()
f = ModelFilter(framework=[args.library.pytorch, args.library.TensorFlow], model_name="bert", tasks=[args.pipeline_tag.Summarization, args.pipeline_tag.TokenClassification])
api.list_models_from_filter(f)
This PR introduces a way to limit the files that will be fetched by the snapshot_download. This is useful when you want to download and cache an entire repository without using git, and that you want to skip files according to their filenames.
espnet. by @Narsil in https://github.com/huggingface/huggingface_hub/pull/542Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.2.1...v0.4.0
This is a patch release fixing an issue with the notebook login.
This is a patch release fixing an issue with the notebook login.
https://github.com/huggingface/huggingface_hub/commit/5e2da9bae95ed4c99683e9572ecc32c9e0da5e15#diff-fb1696cbcf008dd89dde5e8c1da9d4be5a8f7d809bc32f07d4453caba40df15f
Version v0.2.0 introduces the access token compatibility with the hub. It offers the access tokens as the main login handler, with the possibility to
Version v0.2.0 introduces the access token compatibility with the hub. It offers the access tokens as the main login handler, with the possibility to still login with username/password when doing [Ctrl/CMD]+C on the login prompt:
The notebook login is adapted to work with the access tokens.
The Repository class now has an additional parameter, skip_lfs_files, which allows cloning the repository while skipping the large file download.
https://github.com/huggingface/huggingface_hub/pull/472
snapshot_downloadThe snapshot_download method can now take local_files_only as a parameter to enable leveraging previously downloaded files.
https://github.com/huggingface/huggingface_hub/pull/505
clean_ok should be True by default by @LysandreJik in https://github.com/huggingface/huggingface_hub/pull/462
Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.1.1...v0.1.2
Fix typing-extensions minimum version by @lhoestq in https://github.com/huggingface/huggingface_hub/pull/453
create_repo for Repository.clone_from by @sgugger in https://github.com/huggingface/huggingface_hub/pull/459Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.1.0...v0.1.1
Version v0.1.0 is the first minor release of the huggingface_hub package, which promises better stability for the incoming versions. This update comes
Version v0.1.0 is the first minor release of the huggingface_hub package, which promises better stability for the incoming versions. This update comes with big quality of life improvements.
Previously, most methods of the HfApi class required the token to be explicitly passed. This is changed in this version, where it defaults to the token stored in the cache. This results in a re-ordering of arguments, but backward compatibility is preserved in most cases. Where it is not preserved, an explicit error is thrown.
HfApi by @LysandreJik in https://github.com/huggingface/huggingface_hub/pull/388The HfApi class now exposes its methods through the hf_api file, reducing the friction to access these helpers. See the example below:
# Previously
from huggingface_hub import HfApi
api = HfApi()
user = api.whoami()
# Now
from huggingface_hub.hf_api import whoami
user = whoami()
The HfApi can still be imported and works as before for backward compatibility.
list_repo_files util by @sgugger in https://github.com/huggingface/huggingface_hub/pull/395Offers a list_repo_files to ... list the repo files! Supports both model repositories and dataset repositories
model-index, with proper typing by @julien-c in https://github.com/huggingface/huggingface_hub/pull/382Offers a metadata_eval_result in order to generate a YAML block to put in model cards according to evaluation results.
Adds a list_metrics method to HfApi!
Adds a git_prune method to the Repository class. This prunes local files which are unneeded as already pushed to a remote.
It adds the argument auto_lfs_prune to git_push and the commit context-manager for simpler handling.
datasets' push_to_hub method by @LysandreJik in https://github.com/huggingface/huggingface_hub/pull/415Full Changelog: https://github.com/huggingface/huggingface_hub/compare/v0.0.19...v0.1.0
Nothing published for this version
The version v0.0.18 of the huggingface_hub includes tools to manage repository metadata. The following example reads metadata from a repository:
The version v0.0.18 of the huggingface_hub includes tools to manage repository metadata. The following example reads metadata from a repository:
from huggingface_hub import Repository
repo = Repository("xxx", clone_from="yyy")
data = repo.repocard_metadata_load()
The following example completes that metadata before writing it to the repository locally.
data["license"] = "apache-2.0"
repo.repocard_metadata_save(data)
Tag management is now available! Add, check, delete tags locally or remotely directly from the Repository utility.
The Keras mixin has been revisited:
SavedModel objects rather than .h5 files.The pushing methods now have access to a blocking boolean parameter to indicate whether the push should happen asynchronously.
The pushing methods now have access to a blocking boolean parameter to indicate whether the push should happen
asynchronously.
In order to see if the push has finished or its status code (to spot a failure), one should use the command_queue
property on the Repository object.
For example:
from huggingface_hub import Repository
repo = Repository("<local_folder>", clone_from="<user>/<model_name>")
with repo.commit("Commit message", blocking=False):
# Save data
last_command = repo.command_queue[-1]
# Status of the push command
last_command.status
# Will return the status code
# -> -1 will indicate the push is still ongoing
# -> 0 will indicate the push has completed successfully
# -> non-zero code indicates the error code if there was an error
# if there was an error, the stderr may be inspected
last_command.stderr
# Whether the command finished or if it is still ongoing
last_command.is_done
# Whether the command errored-out.
last_command.failed
When using blocking=False, the commands will be tracked and your script will exit only when all pushes are done, even
if other errors happen in your script (a failed push counts as done).
The huggingface_hub library now has a notebook_login method which can be used to login on notebooks with no access to the shell. In a notebook, login with the following:
from huggingface_hub import notebook_login
notebook_login()
The huggingface_hub version v0.0.16 introduces several quality of life improvements.
The huggingface_hub version v0.0.16 introduces several quality of life improvements.
RepositoryProgress bars are now visible with many git operations, such as pulling, cloning and pushing:
>>> from huggingface_hub import Repository
>>> repo = Repository("local_folder", clone_from="huggingface/CodeBERTa-small-v1")
Cloning https://huggingface.co/huggingface/CodeBERTa-small-v1 into local empty directory.
Download file pytorch_model.bin: 45%|████████████████████████████▋ | 144M/321M [00:13<00:12, 14.7MB/s]
Download file flax_model.msgpack: 42%|██████████████████████████▌ | 134M/319M [00:13<00:13, 14.4MB/s]
There is now branching support in Repository. This will clone the xxx repository and checkout the new-branch revision. If it is an existing branch on the remote, it will checkout that branch. If it is another revision, such as a commit or a tag, it will also checkout that revision.
If the revision does not exist, it will create a branch from the latest commit on the main branch.
>>> from huggingface_hub import Repository
>>> repo = Repository("local", clone_from="xxx", revision="new-branch")
Once the repository is instantiated, it is possible to manually checkout revisions using the git_checkout method. If the revision already exists:
>>> repo.git_checkout("main")
If a branch should be created from the current head in the case that it does not exist:
>>> repo.git_checkout("brand-new-branch", create_branch_ok=True)
Revision `brand-new-branch` does not exist. Created and checked out branch `brand-new-branch`
Finally, the commit context manager has a new branch parameter to specify to which branch the utility should push:
>>> with repo.commit("New commit on branch brand-new-branch", branch="brand-new-branch"):
... # Save any file or model here, it will be committed to that branch.
... torch.save(model.state_dict())
The login system has been redesigned to leverage git-credential instead of a token-based authentication system. It leverages the git-credential store helper. If you're unaware of what this is, you may see the following when logging in with huggingface_hub:
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_|
_| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_|
_| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_|
Username:
Password:
Login successful
Your token has been saved to /root/.huggingface/token
Authenticated through git-crendential store but this isn't the helper defined on your machine.
You will have to re-authenticate when pushing to the Hugging Face Hub. Run the following command in your terminal to set it as the default
git config --global credential.helper store
Running the command git config --global credential.helper store will set this as the default way to handle credentials for git authentication. All repositories instantiated with the Repository utility will have this helper set by default, so no action is required from your part when leveraging it.
The logging system is now similar to the existing logging system in transformers and datasets, based on a logging module that controls the entire library's logging level:
>>> from huggingface_hub import logging
>>> logging.set_verbosity_error()
>>> logging.set_verbosity_info()
Repository #219 (@LysandreJik)model-index, and pipeline/task types #265 (@julien-c)[Docs] Update link to Gradio documentation #206 (@abidlabs)
filename option to lfs_track #212 (@LysandreJik)interfaces -> widgets/lib/interfaces #227 (@mishig25)While the first major version is not out (v1.0.0), you should expect breaking changes and we strongly recommend pinning the library to a specific vers…
dataset_info and list_datasets, documentationDatasets repositories get better support, by first enabling full usage of the Repository class for datasets repositories:
from huggingface_hub import Repository
repo = Repository("local_directory", clone_from="<user>/<model_id>", repo_type="dataset")
Datasets can now be retrieved from the Python runtime using the list_datasets method from the HfApi class:
from huggingface_hub import HfApi
api = HfApi()
datasets = api.list_datasets()
len(datasets)
# 1048 publicly available dataset repositories at the time of writing
Information can be retrieved on specific datasets using the dataset_info method from the HfApi class:
from huggingface_hub import HfApi
api = HfApi()
api.dataset_info("squad")
# DatasetInfo: {
# id: squad
# lastModified: 2021-07-07T13:18:53.595Z
# tags: ['pretty_name:SQuAD', 'annotations_creators:crowdsourced', 'language_creators:crowdsourced', 'language_creators:found',
# [...]
Version v0.0.14 introduces a wrapper client for the Inference API. No need to use custom-made requests anymore. See below for an example.
from huggingface_hub import InferenceApi
api = InferenceApi("bert-base-uncased")
api(inputs="The [MASK] is great")
# [
# {'sequence': 'the music is great', 'score': 0.03599703311920166, 'token': 2189, 'token_str': 'music'},
# {'sequence': 'the price is great', 'score': 0.02146693877875805, 'token': 3976, 'token_str': 'price'},
# {'sequence': 'the money is great', 'score': 0.01866752654314041, 'token': 2769, 'token_str': 'money'},
# {'sequence': 'the fun is great', 'score': 0.01654735580086708, 'token': 4569, 'token_str': 'fun'},
# {'sequence': 'the effect is great', 'score': 0.015102624893188477, 'token': 3466, 'token_str': 'effect'}
# ]
Version v0.0.14 introduces an auto-tracking mechanism with git-lfs for large files. Files that are larger than 10MB can be automatically tracked by using the auto_track_large_files method:
from huggingface_hub import Repository
repo = Repository("local_directory", clone_from="<user>/<model_id>")
# save large files in `local_directory`
repo.git_add()
repo.auto_track_large_files()
repo.git_commit("Add large files")
repo.git_push()
# No push rejected error anymore!
It is automatically used when leveraging the commit context manager:
from huggingface_hub import Repository
repo = Repository("local_directory", clone_from="<user>/<model_id>")
with repo.commit("Add large files"):
# add large files
# No push rejected error anymore!
Reminder: the huggingface_hub library follows semantic versioning and is undergoing active development. While the first major version is not out (v1.0.0), you should expect breaking changes and we strongly recommend pinning the library to a specific version.
Two breaking changes are introduced with version v0.0.14.
whoami return changes from a tuple to a dictionaryThe whoami method changes its returned value from a tuple of (<user>, [<organisations>]) to a dictionary containing a lot more information:
In versions v0.0.13 and below, here was the behavior of the whoami method from the HfApi class:
from huggingface_hub import HfFolder, HfApi
api = HfApi()
api.whoami(HfFolder.get_token())
# ('<user>', ['<org_0>', '<org_1>'])
In version v0.0.14, this is updated to the following:
from huggingface_hub import HfFolder, HfApi
api = HfApi()
api.whoami(HfFolder.get_token())
# {
# 'type': str,
# 'name': str,
# 'fullname': str,
# 'email': str,
# 'emailVerified': bool,
# 'apiToken': str,
# `plan': str,
# 'avatarUrl': str,
# 'orgs': List[str]
# }
Repository's use_auth_token initialization parameter now defaults to True.The use_auth_token initialization parameter of the Repository class now defaults to True. The behavior is unchanged if users are not logged in, at which point Repository remains agnostic to the huggingface_hub.
audio-to-audio. #94 (@Narsil)rmdir api-inference-community/src/sentence-transformers #188 (@Pierrci)--no_renames argument to list deleted files. #205 (@LysandreJik)Version 0.0.13 introduces a context manager to save files directly to the Hub. See below for some examples.
Version 0.0.13 introduces a context manager to save files directly to the Hub. See below for some examples.
from huggingface_hub import Repository
repo = Repository("text-files", clone_from="<user>/text-files", use_auth_token=True)
with repo.commit("My first file."):
with open("file.txt", "w+") as f:
f.write(json.dumps({"key": "value"}))
torch.save statement:import torch
from huggingface_hub import Repository
model = torch.nn.Transformer()
repo = Repository("torch-files", clone_from="<user>/torch-files", use_auth_token=True)
with repo.commit("Adding my cool model!"):
torch.save(model.state_dict(), "model.pt")
from flax import serialization
from jax import random
from flax import linen as nn
from huggingface_hub import Repository
model = nn.Dense(features=5)
key1, key2 = random.split(random.PRNGKey(0))
x = random.normal(key1, (10,))
params = model.init(key2, x)
bytes_output = serialization.to_bytes(params)
repo = Repository("flax-model", clone_from="<user>/flax-model", use_auth_token=True)
with repo.commit("Adding my cool Flax model!"):
with open("flax_model.msgpack", "wb") as f:
f.write(bytes_output)
Patches an issue when cloning a repository twice.
Patches an issue when cloning a repository twice.
The huggingface_hub documentation is now available on hf.co/docs! Additionally, a new step-by-step guide to adding libraries is available.
hf_hub_download and Repository power-upThe huggingface_hub documentation is now available on hf.co/docs! Additionally, a new step-by-step guide to adding libraries is available.
hf_hub_downloadA new method is introduced: hf_hub_download. It is the equivalent of doing cached_download(hf_hub_url()), in a single method.
Repository power-upThe Repository class is updated to behave more similarly to git. It is now impossible to clone a repository in a folder that already contains files.
The PyTorch Mixin contributed by @vasudevgupta7 is slightly updated to have the push_to_hub method manage a repository as one would from the command line.
audio-to-audio task. #93 (@Narsil)rmtree issue on windows #105 (@SBrandeis)subprocess.run #104 (@SBrandeis)tags can be undefined #107 (@Pierrci)upload_file docs #136 (@LysandreJik)v0.0.10 Signs the merging of three components of the HuggingFace stack: the huggingface_hub repository is now the central platform to contribute new l
huggingface_hub with api-inference-community and hub interfacesv0.0.10 Signs the merging of three components of the HuggingFace stack: the huggingface_hub repository is now the central platform to contribute new libraries to be supported on the hub.
It regroups three previously separated components:
huggingface_hub Python library, as the Python library to download, upload, and retrieve information from the hub.api-inference-community, as the platform where libraries wishing for hub support may be added.interfaces, as the definition for pipeline types as well as default widget inputs and definitions/UI elements for third-party libraries.Future efforts will be focused on further easing contributing third-party libraries to the Hugging Face Hub
widgets-server #50 (@julien-c)api-inference-community to huggingface_hub. #48 (@Narsil)Implementation of an endpoint to programmatically upload (large) files to any repo on the hub, without the need for git, using HTTP POST requests.
Implementation of an endpoint to programmatically upload (large) files to any repo on the hub, without the need for git, using HTTP POST requests.
HfApi.model_list method now allows multiple filtersModels may now be filtered using several filters:
Example usage:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> # List all models
>>> api.list_models()
>>> # List only the text classification models
>>> api.list_models(filter="text-classification")
>>> # List only the russian models compatible with pytorch
>>> api.list_models(filter=("ru", "pytorch"))
>>> # List only the models trained on the "common_voice" dataset
>>> api.list_models(filter="dataset:common_voice")
>>> # List only the models from the AllenNLP library
>>> api.list_models(filter="allennlp")
filter argument #41 (@LysandreJik)ModelInfo now has a readable representationImprovement of the ModelInfo class so that it displays information about the object.
library_name and library_version in snapshot_download #38 (@LysandreJik)Addition of the HfApi.model_info method to retrieve information about a repo given a revision.
HfApi.model_info method to retrieve information about a repo given a revision.snapshot_download utility to download to cache all files stored in that repo at that given revision.Example usage of HfApi.model_info:
from huggingface_hub import HfApi
hf_api = HfApi()
model_info = hf_api.model_info("lysandre/dummy-hf-hub")
print("Model ID:", model_info.modelId)
for file in model_info.siblings:
print("file:", file.rfilename)
outputs:
Model ID: lysandre/dummy-hf-hub
file: .gitattributes
file: README.md
Example usage of snapshot_download:
from huggingface_hub import snapshot_download
import os
repo_path = snapshot_download("lysandre/dummy-hf-hub")
print(os.listdir(repo_path))
outputs:
['.gitattributes', 'README.md']
Networking improvements by @Pierrci and @lhoestq (#21 and #22)
Networking improvements by @Pierrci and @lhoestq (#21 and #22)
Adding mixin class for ease saving, uploading, downloading a PyTorch model. See PR #11 by @vasudevgupta7
Example usage:
from huggingface_hub import ModelHubMixin
class MyModel(nn.Module, ModelHubMixin):
def __init__(self, **kwargs):
super().__init__()
self.config = kwargs.pop("config", None)
self.layer = ...
def forward(self, ...):
return ...
model = MyModel()
# saving model to local directory & pushing to hub
model.save_pretrained("mymodel", push_to_hub=True, config={"act": "gelu"})
# initiatizing model & loading it from trained-weights
model = MyModel.from_pretrained("username/mymodel@main")
Thanks a ton for your contributions ♥️
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →