HfApi Client
Below is the documentation for the HfApi
class, which serves as a Python wrapper for the Hugging Face Hub’s API.
All methods from the HfApi
are also accessible from the package’s root directly. Both approaches are detailed below.
Using the root method is more straightforward but the HfApi class gives you more flexibility.
In particular, you can pass a token that will be reused in all HTTP calls. This is different
than huggingface-cli login
or login() as the token is not persisted on the machine.
It is also possible to provide a different endpoint or configure a custom user-agent.
from huggingface_hub import HfApi, list_models
# Use root method
models = list_models()
# Or configure a HfApi client
hf_api = HfApi(
endpoint="https://huggingface.co", # Can be a Private Hub endpoint.
token="hf_xxx", # Token is not persisted on the machine.
)
models = hf_api.list_models()
HfApi
class huggingface_hub.HfApi
< source >( endpoint: typing.Optional[str] = None token: typing.Optional[str] = None library_name: typing.Optional[str] = None library_version: typing.Optional[str] = None user_agent: typing.Union[typing.Dict, str, NoneType] = None )
add_space_secret
< source >( repo_id: str key: str value: str token: typing.Optional[str] = None )
Adds or updates a secret in a Space.
Secrets allow to set secret keys or tokens to a Space without hardcoding them. For more details, see https://huggingface.co/docs/hub/spaces-overview#managing-secrets.
change_discussion_status
< source >( repo_id: str discussion_num: int new_status: typing.Literal['open', 'closed'] token: typing.Optional[str] = None comment: typing.Optional[str] = None repo_type: typing.Optional[str] = None ) → DiscussionStatusChange
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
discussion_num (
int
) — The number of the Discussion or Pull Request . Must be a strictly positive integer. -
new_status (
str
) — The new status for the discussion, either"open"
or"closed"
. -
comment (
str
, optional) — An optional comment to post with the status change. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token)
Returns
the status change event
Closes or re-opens a Discussion or Pull Request.
Examples:
>>> new_title = "New title, fixing a typo"
>>> HfApi().rename_discussion(
... repo_id="username/repo_name",
... discussion_num=34
... new_title=new_title
... )
# DiscussionStatusChange(id='deadbeef0000000', type='status-change', ...)
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
comment_discussion
< source >( repo_id: str discussion_num: int comment: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None ) → DiscussionComment
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
discussion_num (
int
) — The number of the Discussion or Pull Request . Must be a strictly positive integer. -
comment (
str
) — The content of the comment to create. Comments support markdown formatting. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token)
Returns
the newly created comment
Creates a new comment on the given Discussion.
Examples:
>>> comment = """
... Hello @otheruser!
...
... # This is a title
...
... **This is bold**, *this is italic* and ~this is strikethrough~
... And [this](http://url) is a link
... """
>>> HfApi().comment_discussion(
... repo_id="username/repo_name",
... discussion_num=34
... comment=comment
... )
# DiscussionComment(id='deadbeef0000000', type='comment', ...)
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
create_branch
< source >( repo_id: str branch: str revision: typing.Optional[str] = None token: typing.Optional[str] = None repo_type: typing.Optional[str] = None exist_ok: bool = False )
Parameters
-
repo_id (
str
) — The repository in which the branch will be created. Example:"user/my-cool-model"
. -
branch (
str
) — The name of the branch to create. -
revision (
str
, optional) — The git revision to create the branch from. It can be a branch name or the OID/SHA of a commit, as a hexadecimal string. Defaults to the head of the"main"
branch. -
token (
str
, optional) — Authentication token. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if creating a branch on a dataset or space,None
or"model"
if tagging a model. Default isNone
. -
exist_ok (
bool
, optional, defaults toFalse
) — IfTrue
, do not raise an error if branch already exists.
Raises
RepositoryNotFoundError or BadRequestError or HfHubHTTPError
- RepositoryNotFoundError — If repository is not found (error 404): wrong repo_id/repo_type, private but not authenticated or repo does not exist.
- BadRequestError —
If invalid reference for a branch. Ex:
refs/pr/5
or ‘refs/foo/bar’. - HfHubHTTPError —
If the branch already exists on the repo (error 409) and
exist_ok
is set toFalse
.
Create a new branch for a repo on the Hub, starting from the specified revision (defaults to main
).
To find a revision suiting your needs, you can use list_repo_refs() or list_repo_commits().
create_commit
< source >( repo_id: str operations: typing.Iterable[typing.Union[huggingface_hub._commit_api.CommitOperationAdd, huggingface_hub._commit_api.CommitOperationDelete]] commit_message: str commit_description: typing.Optional[str] = None token: typing.Optional[str] = None repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None create_pr: typing.Optional[bool] = None num_threads: int = 5 parent_commit: typing.Optional[str] = None ) → CommitInfo
Parameters
-
repo_id (
str
) — The repository in which the commit will be created, for example:"username/custom_transformers"
-
operations (
Iterable
ofCommitOperation()
) — An iterable of operations to include in the commit, either:- CommitOperationAdd to upload a file
- CommitOperationDelete to delete a file
-
commit_message (
str
) — The summary (first line) of the commit that will be created. -
commit_description (
str
, optional) — The description of the commit that will be created -
token (
str
, optional) — Authentication token, obtained withHfApi.login
method. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
revision (
str
, optional) — The git revision to commit from. Defaults to the head of the"main"
branch. -
create_pr (
boolean
, optional) — Whether or not to create a Pull Request with that commit. Defaults toFalse
. Ifrevision
is not set, PR is opened against the"main"
branch. Ifrevision
is set and is a branch, PR is opened against this branch. Ifrevision
is set and is not a branch name (example: a commit oid), anRevisionNotFoundError
is returned by the server. -
num_threads (
int
, optional) — Number of concurrent threads for uploading files. Defaults to 5. Setting it to 2 means at most 2 files will be uploaded concurrently. -
parent_commit (
str
, optional) — The OID / SHA of the parent commit, as a hexadecimal string. Shorthands (7 first characters) are also supported. If specified andcreate_pr
isFalse
, the commit will fail ifrevision
does not point toparent_commit
. If specified andcreate_pr
isTrue
, the pull request will be created fromparent_commit
. Specifyingparent_commit
ensures the repo has not changed before committing the changes, and can be especially useful if the repo is updated / committed to concurrently.
Returns
Instance of CommitInfo containing information about the newly created commit (commit hash, commit url, pr url, commit message,…).
Raises
ValueError
or RepositoryNotFoundError
ValueError
— If commit message is empty.ValueError
— If parent commit is not a valid commit OID.ValueError
— If the Hub API returns an HTTP 400 error (bad request)ValueError
— Ifcreate_pr
isTrue
and revision is neitherNone
nor"main"
.- RepositoryNotFoundError — If repository is not found (error 404): wrong repo_id/repo_type, private but not authenticated or repo does not exist.
Creates a commit in the given repo, deleting & uploading files as needed.
create_commit
assumes that the repo already exists on the Hub. If you get a
Client error 404, please make sure you are authenticated and that repo_id
and
repo_type
are set correctly. If repo does not exist, create it first using
create_repo().
create_commit
is limited to 25k LFS files and a 1GB payload for regular files.
create_commits_on_pr
< source >(
repo_id: str
addition_commits: typing.List[typing.List[huggingface_hub._commit_api.CommitOperationAdd]]
deletion_commits: typing.List[typing.List[huggingface_hub._commit_api.CommitOperationDelete]]
commit_message: str
commit_description: typing.Optional[str] = None
token: typing.Optional[str] = None
repo_type: typing.Optional[str] = None
merge_pr: bool = True
num_threads: int = 5
verbose: bool = False
)
→
str
Parameters
-
repo_id (
str
) — The repository in which the commits will be pushed. Example:"username/my-cool-model"
. -
addition_commits (
List
ofList
of CommitOperationAdd) — A list containing lists of CommitOperationAdd. Each sublist will result in a commit on the PR.deletion_commits — A list containing lists of CommitOperationDelete. Each sublist will result in a commit on the PR. Deletion commits are pushed before addition commits.
-
commit_message (
str
) — The summary (first line) of the commit that will be created. Will also be the title of the PR. -
commit_description (
str
, optional) — The description of the commit that will be created. The description will be added to the PR. -
token (
str
, optional) — Authentication token, obtained withHfApi.login
method. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
merge_pr (
bool
) — If set toTrue
, the Pull Request is merged at the end of the process. Defaults toTrue
. -
num_threads (
int
, optional) — Number of concurrent threads for uploading files. Defaults to 5. -
verbose (
bool
) — If set toTrue
, process will run on verbose mode i.e. print information about the ongoing tasks. Defaults toFalse
.
Returns
str
URL to the created PR.
Raises
MultiCommitException
MultiCommitException
— If an unexpected issue occur in the process: empty commits, unexpected commits in a PR, unexpected PR description, etc.
Push changes to the Hub in multiple commits.
Commits are pushed to a draft PR branch. If the upload fails or gets interrupted, it can be resumed. Progress
is tracked in the PR description. At the end of the process, the PR is set as open and the title is updated to
match the initial commit message. If merge_pr=True
is passed, the PR is merged automatically.
All deletion commits are pushed first, followed by the addition commits. The order of the commits is not guaranteed as we might implement parallel commits in the future. Be sure that your are not updating several times the same file.
create_commits_on_pr
is experimental. Its API and behavior is subject to change in the future without prior notice.
Example:
>>> from huggingface_hub import HfApi, plan_multi_commits
>>> addition_commits, deletion_commits = plan_multi_commits(
... operations=[
... CommitOperationAdd(...),
... CommitOperationAdd(...),
... CommitOperationDelete(...),
... CommitOperationDelete(...),
... CommitOperationAdd(...),
... ],
... )
>>> HfApi().create_commits_on_pr(
... repo_id="my-cool-model",
... addition_commits=addition_commits,
... deletion_commits=deletion_commits,
... (...)
... verbose=True,
... )
create_commits_on_pr
assumes that the repo already exists on the Hub. If you get a Client error 404, please
make sure you are authenticated and that repo_id
and repo_type
are set correctly. If repo does not exist,
create it first using create_repo().
create_discussion
< source >( repo_id: str title: str token: typing.Optional[str] = None description: typing.Optional[str] = None repo_type: typing.Optional[str] = None pull_request: bool = False )
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
title (
str
) — The title of the discussion. It can be up to 200 characters long, and must be at least 3 characters long. Leading and trailing whitespaces will be stripped. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token) -
description (
str
, optional) — An optional description for the Pull Request. Defaults to"Discussion opened with the huggingface_hub Python library"
-
pull_request (
bool
, optional) — Whether to create a Pull Request or discussion. IfTrue
, creates a Pull Request. IfFalse
, creates a discussion. Defaults toFalse
. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
.
Creates a Discussion or Pull Request.
Pull Requests created programmatically will be in "draft"
status.
Creating a Pull Request with changes can also be done at once with HfApi.create_commit().
Returns: DiscussionWithDetails
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
create_pull_request
< source >( repo_id: str title: str token: typing.Optional[str] = None description: typing.Optional[str] = None repo_type: typing.Optional[str] = None )
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
title (
str
) — The title of the discussion. It can be up to 200 characters long, and must be at least 3 characters long. Leading and trailing whitespaces will be stripped. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token) -
description (
str
, optional) — An optional description for the Pull Request. Defaults to"Discussion opened with the huggingface_hub Python library"
-
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
.
Creates a Pull Request . Pull Requests created programmatically will be in "draft"
status.
Creating a Pull Request with changes can also be done at once with HfApi.create_commit();
This is a wrapper around HfApi.create_discussion().
Returns: DiscussionWithDetails
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
create_repo
< source >( repo_id: str token: typing.Optional[str] = None private: bool = False repo_type: typing.Optional[str] = None exist_ok: bool = False space_sdk: typing.Optional[str] = None space_hardware: typing.Optional[str] = None ) → RepoUrl
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token) -
private (
bool
, optional, defaults toFalse
) — Whether the model repo should be private. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
exist_ok (
bool
, optional, defaults toFalse
) — IfTrue
, do not raise an error if repo already exists. -
space_sdk (
str
, optional) — Choice of SDK to use if repo_type is “space”. Can be “streamlit”, “gradio”, “docker”, or “static”. -
space_hardware (
SpaceHardware
orstr
, optional) — Choice of Hardware if repo_type is “space”. See SpaceHardware for a complete list.
Returns
URL to the newly created repo. Value is a subclass of str
containing
attributes like endpoint
, repo_type
and repo_id
.
Create an empty repo on the HuggingFace Hub.
create_tag
< source >( repo_id: str tag: str tag_message: typing.Optional[str] = None revision: typing.Optional[str] = None token: typing.Optional[str] = None repo_type: typing.Optional[str] = None exist_ok: bool = False )
Parameters
-
repo_id (
str
) — The repository in which a commit will be tagged. Example:"user/my-cool-model"
. -
tag (
str
) — The name of the tag to create. -
tag_message (
str
, optional) — The description of the tag to create. -
revision (
str
, optional) — The git revision to tag. It can be a branch name or the OID/SHA of a commit, as a hexadecimal string. Shorthands (7 first characters) are also supported. Defaults to the head of the"main"
branch. -
token (
str
, optional) — Authentication token. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if tagging a dataset or space,None
or"model"
if tagging a model. Default isNone
. -
exist_ok (
bool
, optional, defaults toFalse
) — IfTrue
, do not raise an error if tag already exists.
Raises
RepositoryNotFoundError or RevisionNotFoundError or HfHubHTTPError
- RepositoryNotFoundError — If repository is not found (error 404): wrong repo_id/repo_type, private but not authenticated or repo does not exist.
- RevisionNotFoundError — If revision is not found (error 404) on the repo.
- HfHubHTTPError —
If the branch already exists on the repo (error 409) and
exist_ok
is set toFalse
.
Tag a given commit of a repo on the Hub.
dataset_info
< source >( repo_id: str revision: typing.Optional[str] = None timeout: typing.Optional[float] = None files_metadata: bool = False token: typing.Union[bool, str, NoneType] = None ) → hf_api.DatasetInfo
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
revision (
str
, optional) — The revision of the dataset repository from which to get the information. -
timeout (
float
, optional) — Whether to set a timeout for the request to the Hub. -
files_metadata (
bool
, optional) — Whether or not to retrieve metadata for files in the repository (size, LFS metadata, etc). Defaults toFalse
. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
The dataset repository information.
Get info on one specific dataset on huggingface.co.
Dataset can be private if you pass an acceptable token.
Raises the following errors:
- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access. - RevisionNotFoundError If the revision to download from cannot be found.
delete_branch
< source >( repo_id: str branch: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None )
Parameters
-
repo_id (
str
) — The repository in which a branch will be deleted. Example:"user/my-cool-model"
. -
branch (
str
) — The name of the branch to delete. -
token (
str
, optional) — Authentication token. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if creating a branch on a dataset or space,None
or"model"
if tagging a model. Default isNone
.
Raises
- RepositoryNotFoundError — If repository is not found (error 404): wrong repo_id/repo_type, private but not authenticated or repo does not exist.
- HfHubHTTPError —
If trying to delete a protected branch. Ex:
main
cannot be deleted. - HfHubHTTPError — If trying to delete a branch that does not exist.
Delete a branch from a repo on the Hub.
delete_file
< source >( path_in_repo: str repo_id: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None commit_message: typing.Optional[str] = None commit_description: typing.Optional[str] = None create_pr: typing.Optional[bool] = None parent_commit: typing.Optional[str] = None )
Parameters
-
path_in_repo (
str
) — Relative filepath in the repo, for example:"checkpoints/1fec34a/weights.bin"
-
repo_id (
str
) — The repository from which the file will be deleted, for example:"username/custom_transformers"
-
token (
str
, optional) — Authentication token, obtained withHfApi.login
method. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if the file is in a dataset or space,None
or"model"
if in a model. Default isNone
. -
revision (
str
, optional) — The git revision to commit from. Defaults to the head of the"main"
branch. -
commit_message (
str
, optional) — The summary / title / first line of the generated commit. Defaults tof"Delete {path_in_repo} with huggingface_hub"
. -
commit_description (
str
optional) — The description of the generated commit -
create_pr (
boolean
, optional) — Whether or not to create a Pull Request with that commit. Defaults toFalse
. Ifrevision
is not set, PR is opened against the"main"
branch. Ifrevision
is set and is a branch, PR is opened against this branch. Ifrevision
is set and is not a branch name (example: a commit oid), anRevisionNotFoundError
is returned by the server. -
parent_commit (
str
, optional) — The OID / SHA of the parent commit, as a hexadecimal string. Shorthands (7 first characters) are also supported. If specified andcreate_pr
isFalse
, the commit will fail ifrevision
does not point toparent_commit
. If specified andcreate_pr
isTrue
, the pull request will be created fromparent_commit
. Specifyingparent_commit
ensures the repo has not changed before committing the changes, and can be especially useful if the repo is updated / committed to concurrently.
Deletes a file in the given repo.
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access. - RevisionNotFoundError If the revision to download from cannot be found.
- EntryNotFoundError If the file to download cannot be found.
delete_folder
< source >( path_in_repo: str repo_id: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None revision: typing.Optional[str] = None commit_message: typing.Optional[str] = None commit_description: typing.Optional[str] = None create_pr: typing.Optional[bool] = None parent_commit: typing.Optional[str] = None )
Parameters
-
path_in_repo (
str
) — Relative folder path in the repo, for example:"checkpoints/1fec34a"
. -
repo_id (
str
) — The repository from which the folder will be deleted, for example:"username/custom_transformers"
-
token (
str
, optional) — Authentication token, obtained withHfApi.login
method. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if the folder is in a dataset or space,None
or"model"
if in a model. Default isNone
. -
revision (
str
, optional) — The git revision to commit from. Defaults to the head of the"main"
branch. -
commit_message (
str
, optional) — The summary / title / first line of the generated commit. Defaults tof"Delete folder {path_in_repo} with huggingface_hub"
. -
commit_description (
str
optional) — The description of the generated commit. -
create_pr (
boolean
, optional) — Whether or not to create a Pull Request with that commit. Defaults toFalse
. Ifrevision
is not set, PR is opened against the"main"
branch. Ifrevision
is set and is a branch, PR is opened against this branch. Ifrevision
is set and is not a branch name (example: a commit oid), anRevisionNotFoundError
is returned by the server. -
parent_commit (
str
, optional) — The OID / SHA of the parent commit, as a hexadecimal string. Shorthands (7 first characters) are also supported. If specified andcreate_pr
isFalse
, the commit will fail ifrevision
does not point toparent_commit
. If specified andcreate_pr
isTrue
, the pull request will be created fromparent_commit
. Specifyingparent_commit
ensures the repo has not changed before committing the changes, and can be especially useful if the repo is updated / committed to concurrently.
Deletes a folder in the given repo.
Simple wrapper around create_commit() method.
delete_repo
< source >( repo_id: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None )
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token) -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model.
Delete a repo from the HuggingFace Hub. CAUTION: this is irreversible.
Raises the following errors:
- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
delete_space_secret
< source >( repo_id: str key: str token: typing.Optional[str] = None )
Deletes a secret from a Space.
Secrets allow to set secret keys or tokens to a Space without hardcoding them. For more details, see https://huggingface.co/docs/hub/spaces-overview#managing-secrets.
delete_tag
< source >( repo_id: str tag: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None )
Parameters
-
repo_id (
str
) — The repository in which a tag will be deleted. Example:"user/my-cool-model"
. -
tag (
str
) — The name of the tag to delete. -
token (
str
, optional) — Authentication token. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if tagging a dataset or space,None
or"model"
if tagging a model. Default isNone
.
Raises
- RepositoryNotFoundError — If repository is not found (error 404): wrong repo_id/repo_type, private but not authenticated or repo does not exist.
- RevisionNotFoundError — If tag is not found.
Delete a tag from a repo on the Hub.
duplicate_space
< source >( from_id: str to_id: typing.Optional[str] = None private: typing.Optional[bool] = None token: typing.Optional[str] = None exist_ok: bool = False ) → RepoUrl
Parameters
-
from_id (
str
) — ID of the Space to duplicate. Example:"pharma/CLIP-Interrogator"
. -
to_id (
str
, optional) — ID of the new Space. Example:"dog/CLIP-Interrogator"
. If not provided, the new Space will have the same name as the original Space, but in your account. -
private (
bool
, optional) — Whether the new Space should be private or not. Defaults to the same privacy as the original Space. -
token (
str
, optional) — Hugging Face token. Will default to the locally saved token if not provided. -
exist_ok (
bool
, optional, defaults toFalse
) — IfTrue
, do not raise an error if repo already exists.
Returns
URL to the newly created repo. Value is a subclass of str
containing
attributes like endpoint
, repo_type
and repo_id
.
Raises
- —
HTTPError
if the HuggingFace API returned an error
- —
- — RepositoryNotFoundError
If one of
from_id
orto_id
cannot be found. This may be because it doesn’t exist, or because it is set toprivate
and you do not have access.
- — RepositoryNotFoundError
If one of
Duplicate a Space.
Programmatically duplicate a Space. The new Space will be created in your account and will be in the same state as the original Space (running or paused). You can duplicate a Space no matter the current state of a Space.
Example:
>>> from huggingface_hub import duplicate_space
# Duplicate a Space to your account
>>> duplicate_space("multimodalart/dreambooth-training")
RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...)
# Can set custom destination id and visibility flag.
>>> duplicate_space("multimodalart/dreambooth-training", to_id="my-dreambooth", private=True)
RepoUrl('https://huggingface.co/spaces/nateraw/my-dreambooth',...)
edit_discussion_comment
< source >( repo_id: str discussion_num: int comment_id: str new_content: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None ) → DiscussionComment
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
discussion_num (
int
) — The number of the Discussion or Pull Request . Must be a strictly positive integer. -
comment_id (
str
) — The ID of the comment to edit. -
new_content (
str
) — The new content of the comment. Comments support markdown formatting. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token)
Returns
the edited comment
Edits a comment on a Discussion / Pull Request.
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
Gets all valid dataset tags as a nested namespace object.
get_discussion_details
< source >( repo_id: str discussion_num: int repo_type: typing.Optional[str] = None token: typing.Optional[str] = None )
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
discussion_num (
int
) — The number of the Discussion or Pull Request . Must be a strictly positive integer. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token)
Fetches a Discussion’s / Pull Request ‘s details from the Hub.
Returns: DiscussionWithDetails
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
get_full_repo_name
< source >(
model_id: str
organization: typing.Optional[str] = None
token: typing.Union[bool, str, NoneType] = None
)
→
str
Parameters
-
model_id (
str
) — The name of the model. -
organization (
str
, optional) — If passed, the repository name will be in the organization namespace instead of the user namespace. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
str
The repository name in the user’s namespace ({username}/{model_id}) if no organization is passed, and under the organization namespace ({organization}/{model_id}) otherwise.
Returns the repository name for a given model ID and optional organization.
Gets all valid model tags as a nested namespace object
get_repo_discussions
< source >(
repo_id: str
repo_type: typing.Optional[str] = None
token: typing.Optional[str] = None
)
→
Iterator[Discussion]
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if fetching from a dataset or space,None
or"model"
if fetching from a model. Default isNone
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token).
Returns
Iterator[Discussion]
An iterator of Discussion objects.
Fetches Discussions and Pull Requests for the given repo.
Example:
get_space_runtime
< source >( repo_id: str token: typing.Optional[str] = None ) → SpaceRuntime
Gets runtime information about a Space.
hide_discussion_comment
< source >( repo_id: str discussion_num: int comment_id: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None ) → DiscussionComment
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
discussion_num (
int
) — The number of the Discussion or Pull Request . Must be a strictly positive integer. -
comment_id (
str
) — The ID of the comment to edit. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token)
Returns
the hidden comment
Hides a comment on a Discussion / Pull Request.
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
like
< source >( repo_id: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None )
Parameters
-
repo_id (
str
) — The repository to like. Example:"user/my-cool-model"
. -
token (
str
, optional) — Authentication token. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if liking a dataset or space,None
or"model"
if liking a model. Default isNone
.
Raises
- RepositoryNotFoundError — If repository is not found (error 404): wrong repo_id/repo_type, private but not authenticated or repo does not exist.
Like a given repo on the Hub (e.g. set as favorite).
See also unlike() and list_liked_repos().
list_datasets
< source >(
filter: typing.Union[huggingface_hub.utils.endpoint_helpers.DatasetFilter, str, typing.Iterable[str], NoneType] = None
author: typing.Optional[str] = None
search: typing.Optional[str] = None
sort: typing.Union[typing.Literal['lastModified'], str, NoneType] = None
direction: typing.Optional[typing.Literal[-1]] = None
limit: typing.Optional[int] = None
cardData: typing.Optional[bool] = None
full: typing.Optional[bool] = None
token: typing.Optional[str] = None
)
→
List[DatasetInfo]
Parameters
-
filter (DatasetFilter or
str
orIterable
, optional) — A string or DatasetFilter which can be used to identify datasets on the hub. -
author (
str
, optional) — A string which identify the author of the returned datasets. -
search (
str
, optional) — A string that will be contained in the returned datasets. -
sort (
Literal["lastModified"]
orstr
, optional) — The key with which to sort the resulting datasets. Possible values are the properties of the huggingface_hub.hf_api.DatasetInfo class. -
direction (
Literal[-1]
orint
, optional) — Direction in which to sort. The value-1
sorts by descending order while all other values sort by ascending order. -
limit (
int
, optional) — The limit on the number of datasets fetched. Leaving this option toNone
fetches all datasets. -
full (
bool
, optional) — Whether to fetch all dataset data, including thelastModified
and thecardData
. Can contain useful information such as the PapersWithCode ID. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
List[DatasetInfo]
a list of huggingface_hub.hf_api.DatasetInfo objects. To anticipate future pagination, please consider the return value to be a simple iterator.
Get the list of all the datasets on huggingface.co
Example usage with the filter
argument:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> # List all datasets
>>> api.list_datasets()
>>> # Get all valid search arguments
>>> args = DatasetSearchArguments()
>>> # List only the text classification datasets
>>> api.list_datasets(filter="task_categories:text-classification")
>>> # Using the `DatasetFilter`
>>> filt = DatasetFilter(task_categories="text-classification")
>>> # With `DatasetSearchArguments`
>>> filt = DatasetFilter(task=args.task_categories.text_classification)
>>> api.list_models(filter=filt)
>>> # List only the datasets in russian for language modeling
>>> api.list_datasets(
... filter=("language:ru", "task_ids:language-modeling")
... )
>>> # Using the `DatasetFilter`
>>> filt = DatasetFilter(language="ru", task_ids="language-modeling")
>>> # With `DatasetSearchArguments`
>>> filt = DatasetFilter(
... language=args.language.ru,
... task_ids=args.task_ids.language_modeling,
... )
>>> api.list_datasets(filter=filt)
Example usage with the search
argument:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> # List all datasets with "text" in their name
>>> api.list_datasets(search="text")
>>> # List all datasets with "text" in their name made by google
>>> api.list_datasets(search="text", author="google")
list_files_info
< source >(
repo_id: str
paths: typing.Union[typing.List[str], str, NoneType] = None
revision: typing.Optional[str] = None
repo_type: typing.Optional[str] = None
token: typing.Union[bool, str, NoneType] = None
)
→
Iterable[RepoFile]
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
paths (
Union[List[str], str, None]
, optional) — The paths to get information about. Paths to files are directly resolved. Paths to folders are resolved recursively which means that information is returned about all files in the folder and its subfolders. IfNone
, all files are returned (the default). If a path do not exist, it is ignored without raising an exception. -
revision (
str
, optional) — The revision of the repository from which to get the information. Defaults to"main"
branch. -
repo_type (
str
, optional) — The type of the repository from which to get the information ("model"
,"dataset"
or"space"
. Defaults to"model"
. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
Iterable[RepoFile]
The information about the files, as an iterable of RepoFile
objects. The order of the files is
not guaranteed.
Raises
- RepositoryNotFoundError — If repository is not found (error 404): wrong repo_id/repo_type, private but not authenticated or repo does not exist.
- RevisionNotFoundError — If revision is not found (error 404) on the repo.
List files on a repo and get information about them.
Takes as input a list of paths. Those paths can be either files or folders. Two server endpoints are called:
- POST “/paths-info” to get information about the provided paths. Called once.
- GET “/tree?recursive=True” to paginate over the input folders. Called only if a folder path is provided as input. Will be called multiple times to follow pagination. If no path is provided as input, step 1. is ignored and all files from the repo are listed.
Examples:
Get information about files on a repo.
>>> from huggingface_hub import list_files_info
>>> files_info = list_files_info("lysandre/arxiv-nlp", ["README.md", "config.json"])
>>> files_info
<generator object HfApi.list_files_info at 0x7f93b848e730>
>>> list(files_info)
[
RepoFile: {"blob_id": "43bd404b159de6fba7c2f4d3264347668d43af25", "lfs": None, "rfilename": "README.md", "size": 391},
RepoFile: {"blob_id": "2f9618c3a19b9a61add74f70bfb121335aeef666", "lfs": None, "rfilename": "config.json", "size": 554},
]
List LFS files from the “vae/” folder in “stabilityai/stable-diffusion-2” repository.
>>> from huggingface_hub import list_files_info
>>> [info.rfilename for info in list_files_info("stabilityai/stable-diffusion-2", "vae") if info.lfs is not None]
['vae/diffusion_pytorch_model.bin', 'vae/diffusion_pytorch_model.safetensors']
List all files on a repo.
list_liked_repos
< source >( user: typing.Optional[str] = None token: typing.Optional[str] = None ) → UserLikes
Parameters
-
user (
str
, optional) — Name of the user for which you want to fetch the likes. -
token (
str
, optional) — A valid authentication token (see https://huggingface.co/settings/token). Used only ifuser
is not passed to implicitly determine the current user name.
Returns
object containing the user name and 3 lists of repo ids (1 for models, 1 for datasets and 1 for Spaces).
Raises
ValueError
ValueError
— Ifuser
is not passed and no token found (either from argument or from machine).
List all public repos liked by a user on huggingface.co.
This list is public so token is optional. If user
is not passed, it defaults to
the logged in user.
list_metrics
< source >(
)
→
List[MetricInfo]
Returns
List[MetricInfo]
a list of MetricInfo
objects which.
Get the public list of all the metrics on huggingface.co
list_models
< source >(
filter: typing.Union[huggingface_hub.utils.endpoint_helpers.ModelFilter, str, typing.Iterable[str], NoneType] = None
author: typing.Optional[str] = None
search: typing.Optional[str] = None
emissions_thresholds: typing.Union[typing.Tuple[float, float], NoneType] = None
sort: typing.Union[typing.Literal['lastModified'], str, NoneType] = None
direction: typing.Optional[typing.Literal[-1]] = None
limit: typing.Optional[int] = None
full: typing.Optional[bool] = None
cardData: bool = False
fetch_config: bool = False
token: typing.Union[bool, str, NoneType] = None
)
→
List[ModelInfo]
Parameters
-
filter (ModelFilter or
str
orIterable
, optional) — A string or ModelFilter which can be used to identify models on the Hub. -
author (
str
, optional) — A string which identify the author (user or organization) of the returned models -
search (
str
, optional) — A string that will be contained in the returned model ids. -
emissions_thresholds (
Tuple
, optional) — A tuple of two ints or floats representing a minimum and maximum carbon footprint to filter the resulting models with in grams. -
sort (
Literal["lastModified"]
orstr
, optional) — The key with which to sort the resulting models. Possible values are the properties of the huggingface_hub.hf_api.ModelInfo class. -
direction (
Literal[-1]
orint
, optional) — Direction in which to sort. The value-1
sorts by descending order while all other values sort by ascending order. -
limit (
int
, optional) — The limit on the number of models fetched. Leaving this option toNone
fetches all models. -
full (
bool
, optional) — Whether to fetch all model data, including thelastModified
, thesha
, the files and thetags
. This is set toTrue
by default when using a filter. -
cardData (
bool
, optional) — Whether to grab the metadata for the model as well. Can contain useful information such as carbon emissions, metrics, and datasets trained on. -
fetch_config (
bool
, optional) — Whether to fetch the model configs as well. This is not included infull
due to its size. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
List[ModelInfo]
a list of huggingface_hub.hf_api.ModelInfo objects. To anticipate future pagination, please consider the return value to be a simple iterator.
Get the list of all the models on huggingface.co
Example usage with the filter
argument:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> # List all models
>>> api.list_models()
>>> # Get all valid search arguments
>>> args = ModelSearchArguments()
>>> # List only the text classification models
>>> api.list_models(filter="text-classification")
>>> # Using the `ModelFilter`
>>> filt = ModelFilter(task="text-classification")
>>> # With `ModelSearchArguments`
>>> filt = ModelFilter(task=args.pipeline_tags.TextClassification)
>>> api.list_models(filter=filt)
>>> # Using `ModelFilter` and `ModelSearchArguments` to find text classification in both PyTorch and TensorFlow
>>> filt = ModelFilter(
... task=args.pipeline_tags.TextClassification,
... library=[args.library.PyTorch, args.library.TensorFlow],
... )
>>> api.list_models(filter=filt)
>>> # List only models from the AllenNLP library
>>> api.list_models(filter="allennlp")
>>> # Using `ModelFilter` and `ModelSearchArguments`
>>> filt = ModelFilter(library=args.library.allennlp)
list_repo_commits
< source >( repo_id: str repo_type: typing.Optional[str] = None token: typing.Union[bool, str, NoneType] = None revision: typing.Optional[str] = None formatted: bool = False ) → List[GitCommitInfo]
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if listing commits from a dataset or a Space,None
or"model"
if listing from a model. Default isNone
. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header. -
revision (
str
, optional) — The git revision to commit from. Defaults to the head of the"main"
branch. -
formatted (
bool
) — Whether to return the HTML-formatted title and description of the commits. Defaults to False.
Returns
List[GitCommitInfo]
list of objects containing information about the commits for a repo on the Hub.
Raises
- RepositoryNotFoundError — If repository is not found (error 404): wrong repo_id/repo_type, private but not authenticated or repo does not exist.
- RevisionNotFoundError — If revision is not found (error 404) on the repo.
Get the list of commits of a given revision for a repo on the Hub.
Commits are sorted by date (last commit first).
Example:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
# Commits are sorted by date (last commit first)
>>> initial_commit = api.list_repo_commits("gpt2")[-1]
# Initial commit is always a system commit containing the `.gitattributes` file.
>>> initial_commit
GitCommitInfo(
commit_id='9b865efde13a30c13e0a33e536cf3e4a5a9d71d8',
authors=['system'],
created_at=datetime.datetime(2019, 2, 18, 10, 36, 15, tzinfo=datetime.timezone.utc),
title='initial commit',
message='',
formatted_title=None,
formatted_message=None
)
# Create an empty branch by deriving from initial commit
>>> api.create_branch("gpt2", "new_empty_branch", revision=initial_commit.commit_id)
list_repo_files
< source >(
repo_id: str
revision: typing.Optional[str] = None
repo_type: typing.Optional[str] = None
timeout: typing.Optional[float] = None
token: typing.Union[bool, str, NoneType] = None
)
→
List[str]
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
revision (
str
, optional) — The revision of the model repository from which to get the information. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
List[str]
the list of files in a given repository.
Get the list of files in a given repo.
list_repo_refs
< source >( repo_id: str repo_type: typing.Optional[str] = None token: typing.Union[bool, str, NoneType] = None ) → GitRefs
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if listing refs from a dataset or a Space,None
or"model"
if listing from a model. Default isNone
. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
object containing all information about branches and tags for a repo on the Hub.
Get the list of refs of a given repo (both tags and branches).
Example:
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.list_repo_refs("gpt2")
GitRefs(branches=[GitRefInfo(name='main', ref='refs/heads/main', target_commit='e7da7f221d5bf496a48136c0cd264e630fe9fcc8')], converts=[], tags=[])
>>> api.list_repo_refs("bigcode/the-stack", repo_type='dataset')
GitRefs(
branches=[
GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'),
GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714')
],
converts=[],
tags=[
GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da')
]
)
list_spaces
< source >(
filter: typing.Union[str, typing.Iterable[str], NoneType] = None
author: typing.Optional[str] = None
search: typing.Optional[str] = None
sort: typing.Union[typing.Literal['lastModified'], str, NoneType] = None
direction: typing.Optional[typing.Literal[-1]] = None
limit: typing.Optional[int] = None
datasets: typing.Union[str, typing.Iterable[str], NoneType] = None
models: typing.Union[str, typing.Iterable[str], NoneType] = None
linked: bool = False
full: typing.Optional[bool] = None
token: typing.Optional[str] = None
)
→
List[SpaceInfo]
Parameters
-
filter (
str
orIterable
, optional) — A string tag or list of tags that can be used to identify Spaces on the Hub. -
author (
str
, optional) — A string which identify the author of the returned Spaces. -
search (
str
, optional) — A string that will be contained in the returned Spaces. -
sort (
Literal["lastModified"]
orstr
, optional) — The key with which to sort the resulting Spaces. Possible values are the properties of the huggingface_hub.hf_api.SpaceInfo` class. -
direction (
Literal[-1]
orint
, optional) — Direction in which to sort. The value-1
sorts by descending order while all other values sort by ascending order. -
limit (
int
, optional) — The limit on the number of Spaces fetched. Leaving this option toNone
fetches all Spaces. -
datasets (
str
orIterable
, optional) — Whether to return Spaces that make use of a dataset. The name of a specific dataset can be passed as a string. -
models (
str
orIterable
, optional) — Whether to return Spaces that make use of a model. The name of a specific model can be passed as a string. -
linked (
bool
, optional) — Whether to return Spaces that make use of either a model or a dataset. -
full (
bool
, optional) — Whether to fetch all Spaces data, including thelastModified
and thecardData
. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
List[SpaceInfo]
a list of huggingface_hub.hf_api.SpaceInfo objects. To anticipate future pagination, please consider the return value to be a simple iterator.
Get the public list of all Spaces on huggingface.co
merge_pull_request
< source >( repo_id: str discussion_num: int token: typing.Optional[str] = None comment: typing.Optional[str] = None repo_type: typing.Optional[str] = None ) → DiscussionStatusChange
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
discussion_num (
int
) — The number of the Discussion or Pull Request . Must be a strictly positive integer. -
comment (
str
, optional) — An optional comment to post with the status change. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token)
Returns
the status change event
Merges a Pull Request.
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
model_info
< source >( repo_id: str revision: typing.Optional[str] = None timeout: typing.Optional[float] = None securityStatus: typing.Optional[bool] = None files_metadata: bool = False token: typing.Union[bool, str, NoneType] = None ) → huggingface_hub.hf_api.ModelInfo
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
revision (
str
, optional) — The revision of the model repository from which to get the information. -
timeout (
float
, optional) — Whether to set a timeout for the request to the Hub. -
securityStatus (
bool
, optional) — Whether to retrieve the security status from the model repository as well. -
files_metadata (
bool
, optional) — Whether or not to retrieve metadata for files in the repository (size, LFS metadata, etc). Defaults toFalse
. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
The model repository information.
Get info on one specific model on huggingface.co
Model can be private if you pass an acceptable token or are logged in.
Raises the following errors:
- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access. - RevisionNotFoundError If the revision to download from cannot be found.
move_repo
< source >( from_id: str to_id: str repo_type: typing.Optional[str] = None token: typing.Optional[str] = None )
Parameters
-
from_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. Original repository identifier. -
to_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. Final repository identifier. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token)
Moving a repository from namespace1/repo_name1 to namespace2/repo_name2
Note there are certain limitations. For more information about moving repositories, please see https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo.
Raises the following errors:
- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
pause_space
< source >( repo_id: str token: typing.Optional[str] = None ) → SpaceRuntime
Parameters
-
repo_id (
str
) — ID of the Space to pause. Example:"Salesforce/BLIP2"
. -
token (
str
, optional) — Hugging Face token. Will default to the locally saved token if not provided.
Returns
Runtime information about your Space including stage=PAUSED
and requested hardware.
Raises
RepositoryNotFoundError or HfHubHTTPError or BadRequestError
- RepositoryNotFoundError — If your Space is not found (error 404). Most probably wrong repo_id or your space is private but you are not authenticated.
- HfHubHTTPError — 403 Forbidden: only the owner of a Space can pause it. If you want to manage a Space that you don’t own, either ask the owner by opening a Discussion or duplicate the Space.
- BadRequestError — If your Space is a static Space. Static Spaces are always running and never billed. If you want to hide a static Space, you can set it to private.
Pause your Space.
A paused Space stops executing until manually restarted by its owner. This is different from the sleeping state in which free Spaces go after 48h of inactivity. Paused time is not billed to your account, no matter the hardware you’ve selected. To restart your Space, use restart_space() and go to your Space settings page.
For more details, please visit the docs.
rename_discussion
< source >( repo_id: str discussion_num: int new_title: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None ) → DiscussionTitleChange
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
discussion_num (
int
) — The number of the Discussion or Pull Request . Must be a strictly positive integer. -
new_title (
str
) — The new title for the discussion -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token)
Returns
the title change event
Renames a Discussion.
Examples:
>>> new_title = "New title, fixing a typo"
>>> HfApi().rename_discussion(
... repo_id="username/repo_name",
... discussion_num=34
... new_title=new_title
... )
# DiscussionTitleChange(id='deadbeef0000000', type='title-change', ...)
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
repo_info
< source >(
repo_id: str
revision: typing.Optional[str] = None
repo_type: typing.Optional[str] = None
timeout: typing.Optional[float] = None
files_metadata: bool = False
token: typing.Union[bool, str, NoneType] = None
)
→
Union[SpaceInfo, DatasetInfo, ModelInfo]
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
revision (
str
, optional) — The revision of the repository from which to get the information. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if getting repository info from a dataset or a space,None
or"model"
if getting repository info from a model. Default isNone
. -
timeout (
float
, optional) — Whether to set a timeout for the request to the Hub. -
files_metadata (
bool
, optional) — Whether or not to retrieve metadata for files in the repository (size, LFS metadata, etc). Defaults toFalse
. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
Union[SpaceInfo, DatasetInfo, ModelInfo]
The repository information, as a huggingface_hub.hf_api.DatasetInfo, huggingface_hub.hf_api.ModelInfo or huggingface_hub.hf_api.SpaceInfo object.
Get the info object for a given repo of a given type.
Raises the following errors:
- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access. - RevisionNotFoundError If the revision to download from cannot be found.
request_space_hardware
< source >( repo_id: str hardware: SpaceHardware token: typing.Optional[str] = None sleep_time: typing.Optional[int] = None ) → SpaceRuntime
Parameters
-
repo_id (
str
) — ID of the repo to update. Example:"bigcode/in-the-stack"
. -
hardware (
str
or SpaceHardware) — Hardware on which to run the Space. Example:"t4-medium"
. -
token (
str
, optional) — Hugging Face token. Will default to the locally saved token if not provided. -
sleep_time (
int
, optional) — Number of seconds of inactivity to wait before a Space is put to sleep. Set to-1
if you don’t want your Space to sleep (default behavior for upgraded hardware). For free hardware, you can’t configure the sleep time (value is fixed to 48 hours of inactivity). See https://huggingface.co/docs/hub/spaces-gpus#sleep-time for more details.
Returns
Runtime information about a Space including Space stage and hardware.
Request new hardware for a Space.
It is also possible to request hardware directly when creating the Space repo! See create_repo() for details.
restart_space
< source >( repo_id: str token: typing.Optional[str] = None ) → SpaceRuntime
Parameters
-
repo_id (
str
) — ID of the Space to restart. Example:"Salesforce/BLIP2"
. -
token (
str
, optional) — Hugging Face token. Will default to the locally saved token if not provided.
Returns
Runtime information about your Space.
Raises
RepositoryNotFoundError or HfHubHTTPError or BadRequestError
- RepositoryNotFoundError — If your Space is not found (error 404). Most probably wrong repo_id or your space is private but you are not authenticated.
- HfHubHTTPError — 403 Forbidden: only the owner of a Space can restart it. If you want to restart a Space that you don’t own, either ask the owner by opening a Discussion or duplicate the Space.
- BadRequestError — If your Space is a static Space. Static Spaces are always running and never billed. If you want to hide a static Space, you can set it to private.
Restart your Space.
This is the only way to programmatically restart a Space if you’ve put it on Pause (see pause_space()). You must be the owner of the Space to restart it. If you are using an upgraded hardware, your account will be billed as soon as the Space is restarted. You can trigger a restart no matter the current state of a Space.
For more details, please visit the docs.
set_space_sleep_time
< source >( repo_id: str sleep_time: int token: typing.Optional[str] = None ) → SpaceRuntime
Parameters
-
repo_id (
str
) — ID of the repo to update. Example:"bigcode/in-the-stack"
. -
sleep_time (
int
, optional) — Number of seconds of inactivity to wait before a Space is put to sleep. Set to-1
if you don’t want your Space to pause (default behavior for upgraded hardware). For free hardware, you can’t configure the sleep time (value is fixed to 48 hours of inactivity). See https://huggingface.co/docs/hub/spaces-gpus#sleep-time for more details. -
token (
str
, optional) — Hugging Face token. Will default to the locally saved token if not provided.
Returns
Runtime information about a Space including Space stage and hardware.
Set a custom sleep time for a Space running on upgraded hardware..
Your Space will go to sleep after X seconds of inactivity. You are not billed when your Space is in “sleep” mode. If a new visitor lands on your Space, it will “wake it up”. Only upgraded hardware can have a configurable sleep time. To know more about the sleep stage, please refer to https://huggingface.co/docs/hub/spaces-gpus#sleep-time.
It is also possible to set a custom sleep time when requesting hardware with request_space_hardware().
space_info
< source >( repo_id: str revision: typing.Optional[str] = None timeout: typing.Optional[float] = None files_metadata: bool = False token: typing.Union[bool, str, NoneType] = None ) → SpaceInfo
Parameters
-
repo_id (
str
) — A namespace (user or an organization) and a repo name separated by a/
. -
revision (
str
, optional) — The revision of the space repository from which to get the information. -
timeout (
float
, optional) — Whether to set a timeout for the request to the Hub. -
files_metadata (
bool
, optional) — Whether or not to retrieve metadata for files in the repository (size, LFS metadata, etc). Defaults toFalse
. -
token (
bool
orstr
, optional) — A valid authentication token (see https://huggingface.co/settings/token). IfNone
orTrue
and machine is logged in (throughhuggingface-cli login
or login()), token will be retrieved from the cache. IfFalse
, token is not sent in the request header.
Returns
The space repository information.
Get info on one specific Space on huggingface.co.
Space can be private if you pass an acceptable token.
Raises the following errors:
- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access. - RevisionNotFoundError If the revision to download from cannot be found.
unlike
< source >( repo_id: str token: typing.Optional[str] = None repo_type: typing.Optional[str] = None )
Parameters
-
repo_id (
str
) — The repository to unlike. Example:"user/my-cool-model"
. -
token (
str
, optional) — Authentication token. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if unliking a dataset or space,None
or"model"
if unliking a model. Default isNone
.
Raises
- RepositoryNotFoundError — If repository is not found (error 404): wrong repo_id/repo_type, private but not authenticated or repo does not exist.
Unlike a given repo on the Hub (e.g. remove from favorite list).
See also like() and list_liked_repos().
update_repo_visibility
< source >( repo_id: str private: bool = False token: typing.Optional[str] = None organization: typing.Optional[str] = None repo_type: typing.Optional[str] = None name: typing.Optional[str] = None )
Parameters
-
repo_id (
str
, optional) — A namespace (user or an organization) and a repo name separated by a/
. -
private (
bool
, optional, defaults toFalse
) — Whether the model repo should be private. -
token (
str
, optional) — An authentication token (See https://huggingface.co/settings/token) -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
.
Update the visibility setting of a repository.
Raises the following errors:
- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access.
upload_file
< source >(
path_or_fileobj: typing.Union[str, pathlib.Path, bytes, typing.BinaryIO]
path_in_repo: str
repo_id: str
token: typing.Optional[str] = None
repo_type: typing.Optional[str] = None
revision: typing.Optional[str] = None
commit_message: typing.Optional[str] = None
commit_description: typing.Optional[str] = None
create_pr: typing.Optional[bool] = None
parent_commit: typing.Optional[str] = None
)
→
str
Parameters
-
path_or_fileobj (
str
,Path
,bytes
, orIO
) — Path to a file on the local machine or binary data stream / fileobj / buffer. -
path_in_repo (
str
) — Relative filepath in the repo, for example:"checkpoints/1fec34a/weights.bin"
-
repo_id (
str
) — The repository to which the file will be uploaded, for example:"username/custom_transformers"
-
token (
str
, optional) — Authentication token, obtained withHfApi.login
method. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
revision (
str
, optional) — The git revision to commit from. Defaults to the head of the"main"
branch. -
commit_message (
str
, optional) — The summary / title / first line of the generated commit -
commit_description (
str
optional) — The description of the generated commit -
create_pr (
boolean
, optional) — Whether or not to create a Pull Request with that commit. Defaults toFalse
. Ifrevision
is not set, PR is opened against the"main"
branch. Ifrevision
is set and is a branch, PR is opened against this branch. Ifrevision
is set and is not a branch name (example: a commit oid), anRevisionNotFoundError
is returned by the server. -
parent_commit (
str
, optional) — The OID / SHA of the parent commit, as a hexadecimal string. Shorthands (7 first characters) are also supported. If specified andcreate_pr
isFalse
, the commit will fail ifrevision
does not point toparent_commit
. If specified andcreate_pr
isTrue
, the pull request will be created fromparent_commit
. Specifyingparent_commit
ensures the repo has not changed before committing the changes, and can be especially useful if the repo is updated / committed to concurrently.
Returns
str
The URL to visualize the uploaded file on the hub
Upload a local file (up to 50 GB) to the given repo. The upload is done through a HTTP post request, and doesn’t require git or git-lfs to be installed.
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid- RepositoryNotFoundError
If the repository to download from cannot be found. This may be because it doesn’t exist,
or because it is set to
private
and you do not have access. - RevisionNotFoundError If the revision to download from cannot be found.
upload_file
assumes that the repo already exists on the Hub. If you get a
Client error 404, please make sure you are authenticated and that repo_id
and
repo_type
are set correctly. If repo does not exist, create it first using
create_repo().
Example:
>>> from huggingface_hub import upload_file
>>> with open("./local/filepath", "rb") as fobj:
... upload_file(
... path_or_fileobj=fileobj,
... path_in_repo="remote/file/path.h5",
... repo_id="username/my-dataset",
... repo_type="dataset",
... token="my_token",
... )
"https://huggingface.co/datasets/username/my-dataset/blob/main/remote/file/path.h5"
>>> upload_file(
... path_or_fileobj=".\\local\\file\\path",
... path_in_repo="remote/file/path.h5",
... repo_id="username/my-model",
... token="my_token",
... )
"https://huggingface.co/username/my-model/blob/main/remote/file/path.h5"
>>> upload_file(
... path_or_fileobj=".\\local\\file\\path",
... path_in_repo="remote/file/path.h5",
... repo_id="username/my-model",
... token="my_token",
... create_pr=True,
... )
"https://huggingface.co/username/my-model/blob/refs%2Fpr%2F1/remote/file/path.h5"
upload_folder
< source >(
repo_id: str
folder_path: typing.Union[str, pathlib.Path]
path_in_repo: typing.Optional[str] = None
commit_message: typing.Optional[str] = None
commit_description: typing.Optional[str] = None
token: typing.Optional[str] = None
repo_type: typing.Optional[str] = None
revision: typing.Optional[str] = None
create_pr: typing.Optional[bool] = None
parent_commit: typing.Optional[str] = None
allow_patterns: typing.Union[typing.List[str], str, NoneType] = None
ignore_patterns: typing.Union[typing.List[str], str, NoneType] = None
delete_patterns: typing.Union[typing.List[str], str, NoneType] = None
multi_commits: bool = False
multi_commits_verbose: bool = False
)
→
str
Parameters
-
repo_id (
str
) — The repository to which the file will be uploaded, for example:"username/custom_transformers"
-
folder_path (
str
orPath
) — Path to the folder to upload on the local file system -
path_in_repo (
str
, optional) — Relative path of the directory in the repo, for example:"checkpoints/1fec34a/results"
. Will default to the root folder of the repository. -
token (
str
, optional) — Authentication token, obtained withHfApi.login
method. Will default to the stored token. -
repo_type (
str
, optional) — Set to"dataset"
or"space"
if uploading to a dataset or space,None
or"model"
if uploading to a model. Default isNone
. -
revision (
str
, optional) — The git revision to commit from. Defaults to the head of the"main"
branch. -
commit_message (
str
, optional) — The summary / title / first line of the generated commit. Defaults to:f"Upload {path_in_repo} with huggingface_hub"
-
commit_description (
str
optional) — The description of the generated commit -
create_pr (
boolean
, optional) — Whether or not to create a Pull Request with that commit. Defaults toFalse
. Ifrevision
is not set, PR is opened against the"main"
branch. Ifrevision
is set and is a branch, PR is opened against this branch. Ifrevision
is set and is not a branch name (example: a commit oid), anRevisionNotFoundError
is returned by the server. If bothmulti_commits
andcreate_pr
are True, the PR created in the multi-commit process is kept opened. -
parent_commit (
str
, optional) — The OID / SHA of the parent commit, as a hexadecimal string. Shorthands (7 first characters) are also supported. If specified andcreate_pr
isFalse
, the commit will fail ifrevision
does not point toparent_commit
. If specified andcreate_pr
isTrue
, the pull request will be created fromparent_commit
. Specifyingparent_commit
ensures the repo has not changed before committing the changes, and can be especially useful if the repo is updated / committed to concurrently. -
allow_patterns (
List[str]
orstr
, optional) — If provided, only files matching at least one pattern are uploaded. -
ignore_patterns (
List[str]
orstr
, optional) — If provided, files matching any of the patterns are not uploaded. -
delete_patterns (
List[str]
orstr
, optional) — If provided, remote files matching any of the patterns will be deleted from the repo while committing new files. This is useful if you don’t know which files have already been uploaded. Note: to avoid discrepancies the.gitattributes
file is not deleted even if it matches the pattern. -
multi_commits (
bool
) — If True, changes are pushed to a PR using a multi-commit process. Defaults toFalse
. -
multi_commits_verbose (
bool
) — If True andmulti_commits
is used, more information will be displayed to the user.
Returns
str
A URL to visualize the uploaded folder on the hub
Upload a local folder to the given repo. The upload is done through a HTTP requests, and doesn’t require git or git-lfs to be installed.
The structure of the folder will be preserved. Files with the same name already present in the repository will be overwritten. Others will be left untouched.
Use the allow_patterns
and ignore_patterns
arguments to specify which files to upload. These parameters
accept either a single pattern or a list of patterns. Patterns are Standard Wildcards (globbing patterns) as
documented here. If both allow_patterns
and
ignore_patterns
are provided, both constraints apply. By default, all files from the folder are uploaded.
Use the delete_patterns
argument to specify remote files you want to delete. Input type is the same as for
allow_patterns
(see above). If path_in_repo
is also provided, the patterns are matched against paths
relative to this folder. For example, upload_folder(..., path_in_repo="experiment", delete_patterns="logs/*")
will delete any remote file under ./experiment/logs/
. Note that the .gitattributes
file will not be deleted
even if it matches the patterns.
Any .git/
folder present in any subdirectory will be ignored. However, please be aware that the .gitignore
file is not taken into account.
Uses HfApi.create_commit
under the hood.
Raises the following errors:
HTTPError
if the HuggingFace API returned an errorValueError
if some parameter value is invalid
upload_folder
assumes that the repo already exists on the Hub. If you get a Client error 404, please make
sure you are authenticated and that repo_id
and repo_type
are set correctly. If repo does not exist, create
it first using create_repo().
multi_commits
is experimental. Its API and behavior is subject to change in the future without prior notice.
Example:
# Upload checkpoints folder except the log files
>>> upload_folder(
... folder_path="local/checkpoints",
... path_in_repo="remote/experiment/checkpoints",
... repo_id="username/my-dataset",
... repo_type="datasets",
... token="my_token",
... ignore_patterns="**/logs/*.txt",
... )
# "https://huggingface.co/datasets/username/my-dataset/tree/main/remote/experiment/checkpoints"
# Upload checkpoints folder including logs while deleting existing logs from the repo
# Useful if you don't know exactly which log files have already being pushed
>>> upload_folder(
... folder_path="local/checkpoints",
... path_in_repo="remote/experiment/checkpoints",
... repo_id="username/my-dataset",
... repo_type="datasets",
... token="my_token",
... delete_patterns="**/logs/*.txt",
... )
"https://huggingface.co/datasets/username/my-dataset/tree/main/remote/experiment/checkpoints"
# Upload checkpoints folder while creating a PR
>>> upload_folder(
... folder_path="local/checkpoints",
... path_in_repo="remote/experiment/checkpoints",
... repo_id="username/my-dataset",
... repo_type="datasets",
... token="my_token",
... create_pr=True,
... )
"https://huggingface.co/datasets/username/my-dataset/tree/refs%2Fpr%2F1/remote/experiment/checkpoints"
whoami
< source >( token: typing.Optional[str] = None )
Call HF API to know “whoami”.
huggingface_hub.plan_multi_commits
< source >(
operations: typing.Iterable[typing.Union[huggingface_hub._commit_api.CommitOperationAdd, huggingface_hub._commit_api.CommitOperationDelete]]
max_operations_per_commit: int = 50
max_upload_size_per_commit: int = 2147483648
)
→
Tuple[List[List[CommitOperationAdd]], List[List[CommitOperationDelete]]]
Parameters
-
operations (
List
ofCommitOperation()
) — The list of operations to split into commits. -
max_operations_per_commit (
int
) — Maximum number of operations in a single commit. Defaults to 50. -
max_upload_size_per_commit (
int
) — Maximum size to upload (in bytes) in a single commit. Defaults to 2GB. Files bigger than this limit are uploaded, 1 per commit.
Returns
Tuple[List[List[CommitOperationAdd]], List[List[CommitOperationDelete]]]
a tuple. First item is a list of lists of CommitOperationAdd representing the addition commits to push. The second item is a list of lists of CommitOperationDelete representing the deletion commits.
Split a list of operations in a list of commits to perform.
Implementation follows a sub-optimal (yet simple) algorithm:
- Delete operations are grouped together by commits of maximum
max_operations_per_commits
operations. - All additions exceeding
max_upload_size_per_commit
are committed 1 by 1. - All remaining additions are grouped together and split each time the
max_operations_per_commit
or themax_upload_size_per_commit
limit is reached.
We do not try to optimize the splitting to get the lowest number of commits as this is a NP-hard problem (see bin packing problem). For our use case, it is not problematic to use a sub-optimal solution so we favored an easy-to-explain implementation.
plan_multi_commits
is experimental. Its API and behavior is subject to change in the future without prior notice.
Example:
>>> from huggingface_hub import HfApi, plan_multi_commits
>>> addition_commits, deletion_commits = plan_multi_commits(
... operations=[
... CommitOperationAdd(...),
... CommitOperationAdd(...),
... CommitOperationDelete(...),
... CommitOperationDelete(...),
... CommitOperationAdd(...),
... ],
... )
>>> HfApi().create_commits_on_pr(
... repo_id="my-cool-model",
... addition_commits=addition_commits,
... deletion_commits=deletion_commits,
... (...)
... verbose=True,
... )
The initial order of the operations is not guaranteed! All deletions will be performed before additions. If you are not updating multiple times the same file, you are fine.
API Dataclasses
CommitInfo
class huggingface_hub.CommitInfo
< source >( commit_url: str commit_message: str commit_description: str oid: str pr_url: typing.Optional[str] = None )
Parameters
-
commit_url (
str
) — Url where to find the commit. -
commit_message (
str
) — The summary (first line) of the commit that has been created. -
commit_description (
str
) — Description of the commit that has been created. Can be empty. -
oid (
str
) — Commit hash id. Example:"91c54ad1727ee830252e457677f467be0bfd8a57"
. -
pr_url (
str
, optional) — Url to the PR that has been created, if any. Populated whencreate_pr=True
is passed. -
pr_revision (
str
, optional) — Revision of the PR that has been created, if any. Populated whencreate_pr=True
is passed. Example:"refs/pr/1"
. -
pr_num (
int
, optional) — Number of the PR discussion that has been created, if any. Populated whencreate_pr=True
is passed. Can be passed asdiscussion_num
in get_discussion_details(). Example:1
.
Data structure containing information about a newly created commit.
Returned by create_commit().
DatasetInfo
class huggingface_hub.hf_api.DatasetInfo
< source >( id: typing.Optional[str] = None sha: typing.Optional[str] = None lastModified: typing.Optional[str] = None tags: typing.Optional[typing.List[str]] = None siblings: typing.Optional[typing.List[typing.Dict]] = None private: bool = False author: typing.Optional[str] = None description: typing.Optional[str] = None citation: typing.Optional[str] = None cardData: typing.Optional[dict] = None **kwargs )
Parameters
-
id (
str
, optional) — ID of dataset repository. -
sha (
str
, optional) — repo sha at this particular revision -
lastModified (
str
, optional) — date of last commit to repo -
tags (
List[str]
, optional) — List of tags. -
siblings (
List[RepoFile]
, optional) — list of huggingface_hub.hf_api.RepoFile objects that constitute the dataset. -
private (
bool
, optional, defaults toFalse
) — is the repo private -
author (
str
, optional) — repo author -
description (
str
, optional) — Description of the dataset -
citation (
str
, optional) — Dataset citation -
cardData (
Dict
, optional) — Metadata of the model card as a dictionary. -
kwargs (
Dict
, optional) — Kwargs that will be become attributes of the class.
Info about a dataset accessible from huggingface.co
GitRefInfo
class huggingface_hub.GitRefInfo
< source >( data: typing.Dict )
Contains information about a git reference for a repo on the Hub.
GitCommitInfo
class huggingface_hub.GitCommitInfo
< source >( data: typing.Dict )
Parameters
-
commit_id (
str
) — OID of the commit (e.g."e7da7f221d5bf496a48136c0cd264e630fe9fcc8"
) -
authors (
List[str]
) — List of authors of the commit. -
created_at (
datetime
) — Datetime when the commit was created. -
title (
str
) — Title of the commit. This is a free-text value entered by the authors. -
message (
str
) — Description of the commit. This is a free-text value entered by the authors. -
formatted_title (
str
) — Title of the commit formatted as HTML. Only returned ifformatted=True
is set. -
formatted_message (
str
) — Description of the commit formatted as HTML. Only returned ifformatted=True
is set.
Contains information about a git commit for a repo on the Hub. Check out list_repo_commits() for more details.
GitRefs
class huggingface_hub.GitRefs
< source >( branches: typing.List[huggingface_hub.hf_api.GitRefInfo] converts: typing.List[huggingface_hub.hf_api.GitRefInfo] tags: typing.List[huggingface_hub.hf_api.GitRefInfo] )
Parameters
-
branches (
List[GitRefInfo]
) — A list of GitRefInfo containing information about branches on the repo. -
converts (
List[GitRefInfo]
) — A list of GitRefInfo containing information about “convert” refs on the repo. Converts are refs used (internally) to push preprocessed data in Dataset repos. -
tags (
List[GitRefInfo]
) — A list of GitRefInfo containing information about tags on the repo.
Contains information about all git references for a repo on the Hub.
Object is returned by list_repo_refs().
ModelInfo
class huggingface_hub.hf_api.ModelInfo
< source >( modelId: typing.Optional[str] = None sha: typing.Optional[str] = None lastModified: typing.Optional[str] = None tags: typing.Optional[typing.List[str]] = None pipeline_tag: typing.Optional[str] = None siblings: typing.Optional[typing.List[typing.Dict]] = None private: bool = False author: typing.Optional[str] = None config: typing.Optional[typing.Dict] = None securityStatus: typing.Optional[typing.Dict] = None **kwargs )
Parameters
-
modelId (
str
, optional) — ID of model repository. -
sha (
str
, optional) — repo sha at this particular revision -
lastModified (
str
, optional) — date of last commit to repo -
tags (
List[str]
, optional) — List of tags. -
pipeline_tag (
str
, optional) — Pipeline tag to identify the correct widget. -
siblings (
List[RepoFile]
, optional) — list of (huggingface_hub.hf_api.RepoFile) objects that constitute the model. -
private (
bool
, optional, defaults toFalse
) — is the repo private -
author (
str
, optional) — repo author -
config (
Dict
, optional) — Model configuration information -
securityStatus (
Dict
, optional) — Security status of the model. Example:{"containsInfected": False}
-
kwargs (
Dict
, optional) — Kwargs that will be become attributes of the class.
Info about a model accessible from huggingface.co
RepoFile
class huggingface_hub.hf_api.RepoFile
< source >( rfilename: str size: typing.Optional[int] = None blobId: typing.Optional[str] = None lfs: typing.Optional[huggingface_hub.hf_api.BlobLfsInfo] = None **kwargs )
Parameters
- rfilename (str) — file name, relative to the repo root. This is the only attribute that’s guaranteed to be here, but under certain conditions there can certain other stuff.
-
size (
int
, optional) — The file’s size, in bytes. This attribute is present whenfiles_metadata
argument ofrepo_info
is set toTrue
. It’sNone
otherwise. -
blob_id (
str
, optional) — The file’s git OID. This attribute is present whenfiles_metadata
argument ofrepo_info
is set toTrue
. It’sNone
otherwise. -
lfs (
BlobLfsInfo
, optional) — The file’s LFS metadata. This attribute is present whenfiles_metadata
argument ofrepo_info
is set toTrue
and the file is stored with Git LFS. It’sNone
otherwise.
Data structure that represents a public file inside a repo, accessible from huggingface.co
RepoUrl
class huggingface_hub.RepoUrl
< source >( url: typing.Any endpoint: typing.Optional[str] = None )
Parameters
-
url (
Any
) — String value of the repo url. -
endpoint (
str
, optional) — Endpoint of the Hub. Defaults to https://huggingface.co.
Raises
- —
ValueError
If URL cannot be parsed.
- —
- —
ValueError
Ifrepo_type
is unknown.
- —
Subclass of str
describing a repo URL on the Hub.
RepoUrl
is returned by HfApi.create_repo
. It inherits from str
for backward
compatibility. At initialization, the URL is parsed to populate properties:
- endpoint (
str
) - namespace (
Optional[str]
) - repo_name (
str
) - repo_id (
str
) - repo_type (
Literal["model", "dataset", "space"]
) - url (
str
)
Example:
>>> RepoUrl('https://huggingface.co/gpt2')
RepoUrl('https://huggingface.co/gpt2', endpoint='https://huggingface.co', repo_type='model', repo_id='gpt2')
>>> RepoUrl('https://hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://hub-ci.huggingface.co')
RepoUrl('https://hub-ci.huggingface.co/datasets/dummy_user/dummy_dataset', endpoint='https://hub-ci.huggingface.co', repo_type='dataset', repo_id='dummy_user/dummy_dataset')
>>> RepoUrl('hf://datasets/my-user/my-dataset')
RepoUrl('hf://datasets/my-user/my-dataset', endpoint='https://huggingface.co', repo_type='dataset', repo_id='user/dataset')
>>> HfApi.create_repo("dummy_model")
RepoUrl('https://huggingface.co/Wauplin/dummy_model', endpoint='https://huggingface.co', repo_type='model', repo_id='Wauplin/dummy_model')
SpaceInfo
class huggingface_hub.hf_api.SpaceInfo
< source >( id: typing.Optional[str] = None sha: typing.Optional[str] = None lastModified: typing.Optional[str] = None siblings: typing.Optional[typing.List[typing.Dict]] = None private: bool = False author: typing.Optional[str] = None **kwargs )
Parameters
-
id (
str
, optional) — id of space -
sha (
str
, optional) — repo sha at this particular revision -
lastModified (
str
, optional) — date of last commit to repo -
siblings (
List[RepoFile]
, optional) — list ofhuggingface_hub.hf_api.RepoFIle
objects that constitute the Space -
private (
bool
, optional, defaults toFalse
) — is the repo private -
author (
str
, optional) — repo author -
kwargs (
Dict
, optional) — Kwargs that will be become attributes of the class.
Info about a Space accessible from huggingface.co
This is a “dataclass” like container that just sets on itself any attribute passed by the server.
UserLikes
class huggingface_hub.UserLikes
< source >( user: str total: int datasets: typing.List[str] models: typing.List[str] spaces: typing.List[str] )
Parameters
-
user (
str
) — Name of the user for which we fetched the likes. -
total (
int
) — Total number of likes. -
datasets (
List[str]
) — List of datasets liked by the user (as repo_ids). -
models (
List[str]
) — List of models liked by the user (as repo_ids). -
spaces (
List[str]
) — List of spaces liked by the user (as repo_ids).
Contains information about a user likes on the Hub.
CommitOperation
Below are the supported values for CommitOperation()
:
class huggingface_hub.CommitOperationAdd
< source >( path_in_repo: str path_or_fileobj: typing.Union[str, pathlib.Path, bytes, typing.BinaryIO] )
Parameters
-
path_in_repo (
str
) — Relative filepath in the repo, for example:"checkpoints/1fec34a/weights.bin"
-
path_or_fileobj (
str
,Path
,bytes
, orBinaryIO
) — Either:- a path to a local file (as
str
orpathlib.Path
) to upload - a buffer of bytes (
bytes
) holding the content of the file to upload - a “file object” (subclass of
io.BufferedIOBase
), typically obtained withopen(path, "rb")
. It must supportseek()
andtell()
methods.
- a path to a local file (as
Raises
ValueError
ValueError
— Ifpath_or_fileobj
is not one ofstr
,Path
,bytes
orio.BufferedIOBase
.ValueError
— Ifpath_or_fileobj
is astr
orPath
but not a path to an existing file.ValueError
— Ifpath_or_fileobj
is aio.BufferedIOBase
but it doesn’t support bothseek()
andtell()
.
Data structure holding necessary info to upload a file to a repository on the Hub.
as_file
< source >( with_tqdm: bool = False )
A context manager that yields a file-like object allowing to read the underlying
data behind path_or_fileobj
.
Example:
>>> operation = CommitOperationAdd(
... path_in_repo="remote/dir/weights.h5",
... path_or_fileobj="./local/weights.h5",
... )
CommitOperationAdd(path_in_repo='remote/dir/weights.h5', path_or_fileobj='./local/weights.h5')
>>> with operation.as_file() as file:
... content = file.read()
>>> with operation.as_file(with_tqdm=True) as file:
... while True:
... data = file.read(1024)
... if not data:
... break
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]
>>> with operation.as_file(with_tqdm=True) as file:
... requests.put(..., data=file)
config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s]
class huggingface_hub.CommitOperationDelete
< source >( path_in_repo: str is_folder: typing.Union[bool, typing.Literal['auto']] = 'auto' )
Parameters
-
path_in_repo (
str
) — Relative filepath in the repo, for example:"checkpoints/1fec34a/weights.bin"
for a file or"checkpoints/1fec34a/"
for a folder. -
is_folder (
bool
orLiteral["auto"]
, optional) — Whether the Delete Operation applies to a folder or not. If “auto”, the path type (file or folder) is guessed automatically by looking if path ends with a ”/” (folder) or not (file). To explicitly set the path type, you can setis_folder=True
oris_folder=False
.
Data structure holding necessary info to delete a file or a folder from a repository on the Hub.
Token helper
huggingface_hub
stores the authentication information locally so that it may be re-used in subsequent
methods.
It does this using the HfFolder utility, which saves data at the root of the user.
Deletes the token from storage. Does not fail if token does not exist.
Get token or None if not existent.
Note that a token can be also provided using the HUGGING_FACE_HUB_TOKEN
environment variable.
Token is saved in the huggingface home folder. You can configure it by setting
the HF_HOME
environment variable. Previous location was ~/.huggingface/token
.
If token is found in old location but not in new location, it is copied there first.
For more details, see https://github.com/huggingface/huggingface_hub/issues/1232.
Save token, creating folder as needed.
Token is saved in the huggingface home folder. You can configure it by setting
the HF_HOME
environment variable.
Search helpers
Some helpers to filter repositories on the Hub are available in the huggingface_hub
package.
DatasetFilter
class huggingface_hub.DatasetFilter
< source >( author: typing.Optional[str] = None benchmark: typing.Union[typing.List[str], str, NoneType] = None dataset_name: typing.Optional[str] = None language_creators: typing.Union[typing.List[str], str, NoneType] = None language: typing.Union[typing.List[str], str, NoneType] = None multilinguality: typing.Union[typing.List[str], str, NoneType] = None size_categories: typing.Union[typing.List[str], str, NoneType] = None task_categories: typing.Union[typing.List[str], str, NoneType] = None task_ids: typing.Union[typing.List[str], str, NoneType] = None )
Parameters
-
author (
str
, optional) — A string or list of strings that can be used to identify datasets on the Hub by the original uploader (author or organization), such asfacebook
orhuggingface
. -
benchmark (
str
orList
, optional) — A string or list of strings that can be used to identify datasets on the Hub by their official benchmark. -
dataset_name (
str
, optional) — A string or list of strings that can be used to identify datasets on the Hub by its name, such asSQAC
orwikineural
-
language_creators (
str
orList
, optional) — A string or list of strings that can be used to identify datasets on the Hub with how the data was curated, such ascrowdsourced
ormachine_generated
. -
language (
str
orList
, optional) — A string or list of strings representing a two-character language to filter datasets by on the Hub. -
multilinguality (
str
orList
, optional) — A string or list of strings representing a filter for datasets that contain multiple languages. -
size_categories (
str
orList
, optional) — A string or list of strings that can be used to identify datasets on the Hub by the size of the dataset such as100K<n<1M
or1M<n<10M
. -
task_categories (
str
orList
, optional) — A string or list of strings that can be used to identify datasets on the Hub by the designed task, such asaudio_classification
ornamed_entity_recognition
. -
task_ids (
str
orList
, optional) — A string or list of strings that can be used to identify datasets on the Hub by the specific task such asspeech_emotion_recognition
orparaphrase
.
A class that converts human-readable dataset search parameters into ones compatible with the REST API. For all parameters capitalization does not matter.
Examples:
>>> from huggingface_hub import DatasetFilter
>>> # Using author
>>> new_filter = DatasetFilter(author="facebook")
>>> # Using benchmark
>>> new_filter = DatasetFilter(benchmark="raft")
>>> # Using dataset_name
>>> new_filter = DatasetFilter(dataset_name="wikineural")
>>> # Using language_creator
>>> new_filter = DatasetFilter(language_creator="crowdsourced")
>>> # Using language
>>> new_filter = DatasetFilter(language="en")
>>> # Using multilinguality
>>> new_filter = DatasetFilter(multilinguality="multilingual")
>>> # Using size_categories
>>> new_filter = DatasetFilter(size_categories="100K<n<1M")
>>> # Using task_categories
>>> new_filter = DatasetFilter(task_categories="audio_classification")
>>> # Using task_ids
>>> new_filter = DatasetFilter(task_ids="paraphrase")
ModelFilter
class huggingface_hub.ModelFilter
< source >( author: typing.Optional[str] = None library: typing.Union[typing.List[str], str, NoneType] = None language: typing.Union[typing.List[str], str, NoneType] = None model_name: typing.Optional[str] = None task: typing.Union[typing.List[str], str, NoneType] = None trained_dataset: typing.Union[typing.List[str], str, NoneType] = None tags: typing.Union[typing.List[str], str, NoneType] = None )
Parameters
-
author (
str
, optional) — A string that can be used to identify models on the Hub by the original uploader (author or organization), such asfacebook
orhuggingface
. -
library (
str
orList
, optional) — A string or list of strings of foundational libraries models were originally trained from, such as pytorch, tensorflow, or allennlp. -
language (
str
orList
, optional) — A string or list of strings of languages, both by name and country code, such as “en” or “English” -
model_name (
str
, optional) — A string that contain complete or partial names for models on the Hub, such as “bert” or “bert-base-cased” -
task (
str
orList
, optional) — A string or list of strings of tasks models were designed for, such as: “fill-mask” or “automatic-speech-recognition” -
tags (
str
orList
, optional) — A string tag or a list of tags to filter models on the Hub by, such astext-generation
orspacy
. -
trained_dataset (
str
orList
, optional) — A string tag or a list of string tags of the trained dataset for a model on the Hub.
A class that converts human-readable model search parameters into ones compatible with the REST API. For all parameters capitalization does not matter.
>>> from huggingface_hub import ModelFilter
>>> # For the author_or_organization
>>> new_filter = ModelFilter(author_or_organization="facebook")
>>> # For the library
>>> new_filter = ModelFilter(library="pytorch")
>>> # For the language
>>> new_filter = ModelFilter(language="french")
>>> # For the model_name
>>> new_filter = ModelFilter(model_name="bert")
>>> # For the task
>>> new_filter = ModelFilter(task="text-classification")
>>> # Retrieving tags using the `HfApi.get_model_tags` method
>>> from huggingface_hub import HfApi
>>> api = HfApi()
# To list model tags
>>> api.get_model_tags()
# To list dataset tags
>>> api.get_dataset_tags()
>>> new_filter = ModelFilter(tags="benchmark:raft")
>>> # Related to the dataset
>>> new_filter = ModelFilter(trained_dataset="common_voice")
DatasetSearchArguments
class huggingface_hub.DatasetSearchArguments
< source >( api: typing.Optional[ForwardRef('HfApi')] = None )
A nested namespace object holding all possible values for properties of datasets currently hosted in the Hub with tab-completion. If a value starts with a number, it will only exist in the dictionary
Example:
>>> args = DatasetSearchArguments()
>>> args.author.huggingface
'huggingface'
>>> args.language.en
'language:en'
DatasetSearchArguments
is a legacy class meant for exploratory purposes only. Its
initialization requires listing all datasets on the Hub which makes it increasingly
slower as the number of repos on the Hub increases.
ModelSearchArguments
class huggingface_hub.ModelSearchArguments
< source >( api: typing.Optional[ForwardRef('HfApi')] = None )
A nested namespace object holding all possible values for properties of models currently hosted in the Hub with tab-completion. If a value starts with a number, it will only exist in the dictionary
Example:
>>> args = ModelSearchArguments()
>>> args.author.huggingface
'huggingface'
>>> args.language.en
'en'
ModelSearchArguments
is a legacy class meant for exploratory purposes only. Its
initialization requires listing all models on the Hub which makes it increasingly
slower as the number of repos on the Hub increases.