Return the current level for the HuggingFace Hub’s root logger.

Sets the level for the HuggingFace Hub’s root logger.

Sets the verbosity to logging.INFO.

Sets the verbosity to logging.DEBUG.

Sets the verbosity to logging.WARNING.

Sets the verbosity to logging.ERROR.

Disable propagation of the library log outputs. Note that log propagation is disabled by default.

Enable propagation of the library log outputs. Please disable the HuggingFace Hub’s default handler to prevent double logging if the root logger has been configured.

Returns a logger with the specified name. This function is not supposed to be directly accessed by library users.

>>> from huggingface_hub import get_logger

>>> logger = get_logger(__file__)
>>> logger.set_verbosity_info()

Check if progress bars are disabled globally or for a specific group.

This function returns whether progress bars are disabled for a given group or globally. It checks the HF_HUB_DISABLE_PROGRESS_BARS environment variable first, then the programmatic settings.

Disable progress bars either globally or for a specified group.

This function updates the state of progress bars based on a group name. If no group name is provided, all progress bars are disabled. The operation respects the HF_HUB_DISABLE_PROGRESS_BARS environment variable’s setting.

Enable progress bars either globally or for a specified group.

This function sets the progress bars to enabled for the specified group or globally if no group is specified. The operation is subject to the HF_HUB_DISABLE_PROGRESS_BARS environment setting.

Set the HTTP client factory to be used by huggingface_hub.

The client factory is a method that returns a httpx.Client object. On the first call to get_client the client factory will be used to create a new httpx.Client object that will be shared between all calls made by huggingface_hub.

This can be useful if you are running your scripts in a specific environment requiring custom configuration (e.g. custom proxy or certifications).

Use get_client to get a correctly configured httpx.Client.

Get a httpx.Client object, using the transport factory from the user.

This client is shared between all calls made by huggingface_hub. Therefore you should not close it manually.

Use set_client_factory() to customize the httpx.Client.

Close the global httpx.Client used by huggingface_hub.

If a Client is closed, it will be recreated on the next call to get_client.

Can be useful if e.g. an SSL certificate has been updated.

Set the HTTP async client factory to be used by huggingface_hub.

The async client factory is a method that returns a httpx.AsyncClient object. This can be useful if you are running your scripts in a specific environment requiring custom configuration (e.g. custom proxy or certifications). Use get_async_client to get a correctly configured httpx.AsyncClient.

Return a httpx.AsyncClient object, using the transport factory from the user.

Use set_async_client_factory() to customize the httpx.AsyncClient.

Internal version of response.raise_for_status() that will refine a potential HTTPError. Raised exception will be an instance of HfHubHTTPError.

This helper is meant to be the unique method to raise_for_status when making a call to the Hugging Face Hub.

HTTPError to inherit from for any custom HTTP Error raised in HF Hub.

Any HTTPError is converted at least into a HfHubHTTPError. If some information is sent back by the server, it will be added to the error message.

Added details:

• Request id from “X-Request-Id” header if exists. If not, fallback to “X-Amzn-Trace-Id” header if exists.
• Server error message from the header “X-Error-Message”.
• Server error message if we can found one in the response body.

    import httpx
    from huggingface_hub.utils import get_session, hf_raise_for_status, HfHubHTTPError

    response = get_session().post(...)
    try:
        hf_raise_for_status(response)
    except HfHubHTTPError as e:
        print(str(e)) # formatted message
        e.request_id, e.server_message # details returned by server

        # Complete the error message with additional information once it's raised
        e.append_to_message("
ate_commit` expects the repository to exist.")
        raise

Raised when trying to access a hf.co URL with an invalid repository name, or with a private repo name the user does not have access to.

>>> from huggingface_hub import model_info
>>> model_info("<non_existent_repository>")
(...)
huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error. (Request ID: PvMw_VjBMjVdMz53WKIzP)

Repository Not Found for url: https://huggingface.co/api/models/%3Cnon_existent_repository%3E.
Please make sure you specified the correct `repo_id` and `repo_type`.
If the repo is private, make sure you are authenticated.
Invalid username or password.

Raised when trying to access a gated repository for which the user is not on the authorized list.

Note: derives from RepositoryNotFoundError to ensure backward compatibility.

>>> from huggingface_hub import model_info
>>> model_info("<gated_repository>")
(...)
huggingface_hub.errors.GatedRepoError: 403 Client Error. (Request ID: ViT1Bf7O_026LGSQuVqfa)

Cannot access gated repo for url https://huggingface.co/api/models/ardent-figment/gated-model.
Access to model ardent-figment/gated-model is restricted and you are not in the authorized list.
Visit https://huggingface.co/ardent-figment/gated-model to ask for access.

Raised when trying to access a hf.co URL with a valid repository but an invalid revision.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', 'config.json', revision='<non-existent-revision>')
(...)
huggingface_hub.errors.RevisionNotFoundError: 404 Client Error. (Request ID: Mwhe_c3Kt650GcdKEFomX)

Revision Not Found for url: https://huggingface.co/bert-base-cased/resolve/%3Cnon-existent-revision%3E/config.json.

Raised by hf_raise_for_status when the server returns a HTTP 400 error.

>>> resp = httpx.post("hf.co/api/check", ...)
>>> hf_raise_for_status(resp, endpoint_name="check")
huggingface_hub.errors.BadRequestError: Bad request for check endpoint: {details} (Request ID: XXX)

Raised when entry not found, either locally or remotely.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.RemoteEntryNotFoundError (...)
>>> hf_hub_download('bert-base-cased', '<non-existent-file>', local_files_only=True)
(...)
huggingface_hub.utils.errors.LocalEntryNotFoundError (...)

Raised when trying to access a hf.co URL with a valid repository and revision but an invalid filename.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-existent-file>')
(...)
huggingface_hub.errors.EntryNotFoundError: 404 Client Error. (Request ID: 53pNl6M0MxsnG5Sw8JA6x)

Entry Not Found for url: https://huggingface.co/bert-base-cased/resolve/main/%3Cnon-existent-file%3E.

Raised when trying to access a file or snapshot that is not on the disk when network is disabled or unavailable (connection issue). The entry may exist on the Hub.

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download('bert-base-cased', '<non-cached-file>',  local_files_only=True)
(...)
huggingface_hub.errors.LocalEntryNotFoundError: Cannot find the requested files in the disk cache and outgoing traffic has been disabled. To enable hf.co look-ups and downloads online, set 'local_files_only' to False.

Raised when a request is made but HF_HUB_OFFLINE=1 is set as environment variable.

Sends telemetry that helps tracking usage of different HF libraries.

This usage data helps us debug issues and prioritize new features. However, we understand that not everyone wants to share additional information, and we respect your privacy. You can disable telemetry collection by setting the HF_HUB_DISABLE_TELEMETRY=1 as environment variable. Telemetry is also disabled in offline mode (i.e. when setting HF_HUB_OFFLINE=1).

Telemetry collection is run in a separate thread to minimize impact for the user.

>>> from huggingface_hub.utils import send_telemetry

# Send telemetry without library information
>>> send_telemetry("ping")

# Send telemetry to subtopic with library information
>>> send_telemetry("gradio/local_link", library_name="gradio", library_version="3.22.1")

# Send telemetry with additional data
>>> send_telemetry(
...     topic="examples",
...     library_name="transformers",
...     library_version="4.26.0",
...     user_agent={"pipeline": "text_classification", "framework": "flax"},
... )

Validate values received as argument for any public method of huggingface_hub.

The goal of this decorator is to harmonize validation of arguments reused everywhere. By default, all defined validators are tested.

Validators:

• validate_repo_id(): repo_id must be "repo_name" or "namespace/repo_name". Namespace is a username or an organization.
• ~utils.smoothly_deprecate_legacy_arguments: Ignore proxies when downloading files (should be set globally).

>>> from huggingface_hub.utils import validate_hf_hub_args

>>> @validate_hf_hub_args
... def my_cool_method(repo_id: str):
...     print(repo_id)

>>> my_cool_method(repo_id="valid_repo_id")
valid_repo_id

>>> my_cool_method("other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

>>> my_cool_method(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Generic exception thrown by huggingface_hub validators.

Inherits from ValueError.

Validate repo_id is valid.

This is not meant to replace the proper validation made on the Hub but rather to avoid local inconsistencies whenever possible (example: passing repo_type in the repo_id is forbidden).

Rules:

• Between 1 and 96 characters.
• Either “repo_name” or “namespace/repo_name”
• [a-zA-Z0-9] or ”-”, ”_”, ”.”
• ”—” and ”..” are forbidden

Valid: "foo", "foo/bar", "123", "Foo-BAR_foo.bar123"

Not valid: "datasets/foo/bar", ".repo_id", "foo--bar", "foo.git"

>>> from huggingface_hub.utils import validate_repo_id
>>> validate_repo_id(repo_id="valid_repo_id")
>>> validate_repo_id(repo_id="other..repo..id")
huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'.

Discussed in https://github.com/huggingface/huggingface_hub/issues/1008. In moon-landing (internal repository):

• https://github.com/huggingface/moon-landing/blob/main/server/lib/Names.ts#L27
• https://github.com/huggingface/moon-landing/blob/main/server/views/components/NewRepoForm/NewRepoForm.svelte#L138

Smoothly deprecate legacy arguments in the huggingface_hub codebase.

This function ignores some deprecated arguments from the kwargs and warns the user they are ignored. The goal is to avoid breaking existing code while guiding the user to the new way of doing things.

List of deprecated arguments:

• proxies: To set up proxies, user must either use the HTTP_PROXY environment variable or configure the httpx.Client manually using the set_client_factory() function.

  In huggingface_hub 0.x, proxies was a dictionary directly passed to requests.request. In huggingface_hub 1.x, we migrated to httpx which does not support proxies the same way. In particular, it is not possible to configure proxies on a per-request basis. The solution is to configure it globally using the set_client_factory() function or using the HTTP_PROXY environment variable.

  More more details, see:

  • https://www.python-httpx.org/advanced/proxies/
  • https://www.python-httpx.org/compatibility/#proxy-keys.

• resume_download: deprecated without replacement. huggingface_hub always resumes downloads whenever possible.

• force_filename: deprecated without replacement. Filename is always the same as on the Hub.

• local_dir_use_symlinks: deprecated without replacement. Downloading to a local directory does not use symlinks anymore.