pypi huggingface-hub 0.15.1
v0.15.1: InferenceClient and background uploads!

latest releases: 0.21.3, 0.21.2, 0.21.1...
9 months ago


We introduce InferenceClient, a new client to run inference on the Hub. The objective is to:

  • support both InferenceAPI and Inference Endpoints services in a single client.
  • offer a nice interface with:
    • 1 method per task (e.g. summary = client.summarization("this is a long text"))
    • 1 default model per task (i.e. easy to prototype)
    • explicit and documented parameters
    • convenient binary inputs (from url, path, file-like object,...)
  • be flexible and support custom requests if needed

Check out the Inference guide to get a complete overview.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()

>>> image = client.text_to_image("An astronaut riding a horse on the moon.")

>>> client.image_classification("")
[{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...]

The short-term goal is to add support for more tasks (here is the current list), especially text-generation and handle asyncio calls. The mid-term goal is to deprecate and replace InferenceAPI.

Non-blocking uploads

It is now possible to run HfApi calls in the background! The goal is to make it easier to upload files periodically without blocking the main thread during a training. The was previously possible when using Repository but is now available for HTTP-based methods like upload_file, upload_folder and create_commit. If run_as_future=True is passed:

  • the job is queued in a background thread. Only 1 worker is spawned to ensure no race condition. The goal is NOT to speed up a process by parallelizing concurrent calls to the Hub.
  • a Future object is returned to check the job status
  • main thread is not interrupted, even if an exception occurs during the upload

In addition to this parameter, a run_as_future(...) method is available to queue any other calls to the Hub. More details in this guide.

>>> from huggingface_hub import HfApi

>>> api = HfApi()
>>> api.upload_file(...)  # takes Xs
# URL to upload file

>>> future = api.upload_file(..., run_as_future=True) # instant
>>> future.result() # wait until complete
# URL to upload file
  • Run HfApi methods in the background (run_as_future) by @Wauplin in #1458
  • fix docs for run_as_future by @Wauplin (direct commit on main)

Breaking changes

Some (announced) breaking changes have been introduced:

  • list_models, list_datasets and list_spaces return an iterable instead of a list (lazy-loading of paginated results)
  • The parameter cardData in list_datasets has been removed in favor of the parameter full.

Both changes had a deprecation cycle for a few releases now.

Bugfixes and small improvements

Token permission

New parameters in login() :

  • new_session : skip login if new_session=False and user is already logged in
  • write_permission : write permission is required (login fails otherwise)

Also added a new HfApi().get_token_permission() method that returns "read" or "write" (or None if not logged in).

List files with details

New parameter to get more details when listing files: list_repo_files(..., expand=True).
API call is slower but lastCommit and security fields are returned as well.

Docs fixes


  • Fix consistency check when downloading a file by @Wauplin in #1449
  • Fix discussion URL on datasets and spaces by @Wauplin in #1465
  • FIX user agent not passed in snapshot_download by @Wauplin in #1478
  • Avoid ImportError when importing WebhooksServer and Gradio is not installed by @mariosasko in #1482
  • add utf8 encoding when opening files for windows by @abidlabs in #1484
  • Fix incorrect syntax in warning message for _deprecate_list_output() by @x11kjm in #1485
  • Update by @SimonKitSangChu in #1487
  • fix pause_and_restart test by @Wauplin (direct commit on main)
  • Support image-to-image task in InferenceApi by @Wauplin in #1489

Don't miss a new huggingface-hub release

NewReleases is sending notifications on new releases.