Hugging Face Hub

https://huggingface.co/docs/huggingface_hub
Admin
The Hugging Face Hub client library allows Python users to interact with the Hugging Face Hub, a...
Tokens:1,082,907
Snippets:4,902
Trust Score:10
Update:1 day ago
Show doc for...
Tokens:
Raw
### hf extensions install examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of installing extensions from GitHub repositories.

```console
$ hf extensions install hf-claude
```

```console
$ hf extensions install hanouticelina/hf-claude
```

```console
$ hf extensions install alvarobartt/hf-mem
```

--------------------------------

### hf extensions list example

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Example of listing installed extensions.

```console
$ hf extensions list
```

--------------------------------

### hf sandbox spawn examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Two example invocations: one starts a Python HTTP server, the other runs uvicorn with a working directory.

```console
$ hf sandbox spawn <sandbox_id> — python -m http.server 8000
```

```console
$ hf sandbox spawn -w /app <sandbox_id> — uvicorn app:app
```

--------------------------------

### hf buckets create examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of using hf buckets create with various bucket IDs and options.

```console
$ hf buckets create my-bucket
```

```console
$ hf buckets create user/my-bucket
```

```console
$ hf buckets create hf://buckets/user/my-bucket
```

```console
$ hf buckets create user/my-bucket —private
```

```console
$ hf buckets create user/my-bucket —exist-ok
```

```console
$ hf buckets create user/my-bucket —region us
```

--------------------------------

### hf download examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

A series of example invocations of hf download, demonstrating downloading a full repo, specific files, filtering by include/exclude patterns, using a local directory, specifying a repo type, and using a hf:// URI.

```console
$ hf download meta-llama/Llama-3.2-1B-Instruct
```

```console
$ hf download meta-llama/Llama-3.2-1B-Instruct config.json tokenizer.json
```

```console
$ hf download meta-llama/Llama-3.2-1B-Instruct —include ”_.safetensors” —exclude ”_.bin”
```

```console
$ hf download meta-llama/Llama-3.2-1B-Instruct —local-dir ./models/llama
```

```console
$ hf download HuggingFaceM4/FineVision art/ —repo-type dataset
```

```console
$ hf download hf://datasets/HuggingFaceH4/ultrachat_200k
```

--------------------------------

### Async image segmentation example

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client

Run image segmentation asynchronously using AsyncInferenceClient. Requires PIL to be installed (pip install Pillow). The example shows the expected output format.

```python
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.image_segmentation("cat.jpg")
[ImageSegmentationOutputElement(score=0.989008, label='LABEL_184', mask=<PIL.PngImagePlugin.PngImageFile image mode=L size=400x300 at 0x7FDD2B129CC0>), ...]
```

--------------------------------

### hf repos list examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of using hf repos ls: list repos, explore as 3D city, and filter by namespace and search.

```console
$ hf repos ls
```

```console
$ hf repos ls —explore
```

```console
$ hf repos ls —namespace my-org —search bert
```

--------------------------------

### Install huggingface_hub with hf_xet

Source: https://huggingface.co/docs/huggingface_hub/en/guides/download

Install the latest version of `huggingface_hub` to get `hf_xet` as a dependency. As of version 0.32.0, this will also install `hf_xet`.

```bash
pip install -U "huggingface_hub"
```

--------------------------------

### Create and use a dedicated sandbox with Sandbox.create()

Source: https://huggingface.co/docs/huggingface_hub/en/guides/sandbox

Shows the basic usage of Sandbox.create() in a context manager. The sandbox is ready in about 6 seconds, and each command runs in about 100ms. The example runs a Python command and prints its stdout.

```python
>>> from huggingface_hub import Sandbox

>>> with Sandbox.create() as sbx:                      # ready in ~6s
...     result = sbx.run("python -c 'print(40 + 2)'")  # ~100ms per command
...     print(result.stdout)
42
```

--------------------------------

### image_to_image async example

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client

Runs in an async context. Requires PIL installed (pip install Pillow). The example loads 'cat.jpg', applies the prompt 'turn the cat into a tiger', and saves the result as 'tiger.jpg'.

```python
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> image = await client.image_to_image("cat.jpg", prompt="turn the cat into a tiger")
>>> image.save("tiger.jpg")
```

--------------------------------

### hf sandbox create examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of creating sandboxes with different options such as image, flavor, label, and pool.

```console
$ hf sandbox create
```

```console
$ hf sandbox create ubuntu:24.04
```

```console
$ hf sandbox create --flavor a10g-small
```

```console
$ hf sandbox create --label controller-run=run-42
```

```console
$ hf sandbox create --pool pool-ab12cd34ef56 --env LOG_LEVEL=debug
```

--------------------------------

### image_to_image example

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client

Performs image-to-image translation using a specified model. Requires PIL installed (pip install Pillow). The example loads an image from 'cat.jpg', applies the prompt 'turn the cat into a tiger', and saves the result to 'tiger.jpg'.

```python
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> image = client.image_to_image("cat.jpg", prompt="turn the cat into a tiger")
>>> image.save("tiger.jpg")
```

--------------------------------

### Generate, review, and apply a sync plan with hf buckets sync CLI

Source: https://huggingface.co/docs/huggingface_hub/en/guides/buckets

Three-step workflow: generate a plan file with `--plan`, review the JSONL file, then apply it with `--apply`. The plan file contains a header and one line per operation with action, file path, and reason. Nothing is transferred during plan generation.

```bash
# Step 1: Generate a plan file (nothing is transferred)
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl
Sync plan: ./data -> hf://buckets/username/my-bucket
  Uploads: 3
  Downloads: 0
  Deletes: 0
  Skips: 1
Plan saved to: sync-plan.jsonl

# Step 2: Review the plan file (JSONL format)
>>> cat sync-plan.jsonl

# Step 3: Apply the plan
>>> hf buckets sync --apply sync-plan.jsonl
```

--------------------------------

### hf discussions info examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of using hf discussions info to get information in default format or as JSON.

```console
$ hf discussions info username/my-model 5
```

```console
$ hf discussions info username/my-model 5 —format json
```

--------------------------------

### Create a pooled sandbox on demand

Source: https://huggingface.co/docs/huggingface_hub/en/guides/sandbox

Creates a pool without warm-up, then creates a sandbox that boots the first host (~6s), and a second that packs onto the same warm host (~one round-trip, no new VM). Pre-provision hosts with warm_up=N or pool.warm(N) to avoid cold start.

```python
>>> pool = SandboxPool(image="python:3.12", flavor="cpu-basic")
>>> sbx = pool.create()    # boots the first host (~6s)
>>> sbx = pool.create()    # packs onto the same warm host (~one round-trip, no new VM)
```

--------------------------------

### Create, exec, cp, and kill a sandbox

Source: https://huggingface.co/docs/huggingface_hub/en/guides/cli

Shows the basic workflow: create a sandbox (waits until ready, prints its id), attach labels, run commands with streamed output, copy files in/out, and terminate. The `--flavor` flag selects hardware, `--idle-timeout` bounds lifetime, and `-l`/`--label` attach labels.

```bash
# Create a sandbox (waits until it is ready, prints its id)
>>> hf sandbox create
✓ Sandbox ready id=687f911eaea852de79c4a50a image=python:3.12 elapsed=6.0s

# Attach labels to the underlying Job
>>> hf sandbox create --label controller-run=run-42 --label team=data-infra

# Run commands inside it (output is streamed, exit code is propagated)
>>> hf sandbox exec 687f911eaea852de79c4a50a -- python -c "print('hi')"
hi

# Copy files in and out (docker-style)
>>> hf sandbox cp data.csv 687f911eaea852de79c4a50a:/data/data.csv
>>> hf sandbox cp 687f911eaea852de79c4a50a:/app/results.json results.json

# Terminate a sandbox
>>> hf sandbox kill 687f911eaea852de79c4a50a
```

--------------------------------

### Perform image segmentation with InferenceClient

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client

Example usage of the image_segmentation method. Requires PIL to be installed (pip install Pillow). The output is a list of ImageSegmentationOutputElement objects.

```python
>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.image_segmentation("cat.jpg")
[ImageSegmentationOutputElement(score=0.989008, label='LABEL_184', mask=<PIL.PngImagePlugin.PngImageFile image mode=L size=400x300 at 0x7FDD2B129CC0>), ...]
```

--------------------------------

### Get logger example

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/utilities

Example usage of get_logger, a repo-specific helper method not intended for library users. It returns a logger with the specified name and sets verbosity to info.

```python
>>> from huggingface_hub import get_logger

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

--------------------------------

### Example filter file filters.txt

Source: https://huggingface.co/docs/huggingface_hub/en/guides/buckets

Example content of a filter file used with --filter-from. Lines starting with # are comments, and rules are evaluated in order (first matching rule wins).

```text
# filters.txt
- *.log
- *.tmp
+ *.safetensors
+ *.json
```

--------------------------------

### hf repos tag create examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of creating a tag with and without a message.

```console
$ hf repos tag create my-model v1.0
```

```console
$ hf repos tag create my-model v1.0 -m "First release"
```

--------------------------------

### Verify hf CLI installation with hf --help

Source: https://huggingface.co/docs/huggingface_hub/en/guides/cli

Displays the help message listing all available commands and options. If you see 'command not found: hf', refer to the installation guide.

```bash
hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...

  Hugging Face Hub CLI

Options:
  --skills              Print the `hf-cli` SKILL.md to stdout (alias for `hf skills preview`).
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or customize the installation.
  -h, --help            Show this message and exit.

Main commands:
  auth                 Manage authentication (login, logout, etc.).
  buckets              Commands to interact with buckets.
  cache                Manage local cache directory.
  collections          Interact with collections on the Hub.
  datasets             Interact with datasets on the Hub.
  download             Download files from the Hub.
  endpoints            Manage Hugging Face Inference Endpoints.
  extensions           Manage hf CLI extensions.
  jobs                 Run and manage Jobs on the Hub.
  models               Interact with models on the Hub.
  papers               Interact with papers on the Hub.
  repos                Manage repos on the Hub.
  skills               Manage skills for AI assistants.
  spaces               Interact with spaces on the Hub.
  sync                 Sync files between local directory and a bucket.
  upload               Upload a file or a folder to the Hub.

Help commands:
  env      Print information about the environment.
  version  Print information about the hf version.
```

--------------------------------

### hf auth login examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of using hf auth login with various options.

```console
$ hf auth login
```

```console
$ hf auth login —token $HF_TOKEN
```

```console
$ hf auth login —token $HF_TOKEN —add-to-git-credential
```

```console
$ hf auth login —force
```

--------------------------------

### Generate and apply a sync plan with hf buckets sync --plan

Source: https://huggingface.co/docs/huggingface_hub/en/guides/cli

Shows how to generate a plan for review before executing, and then apply it with --apply.

```bash
# Generate a plan
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl

# Review and apply the plan
>>> hf buckets sync --apply sync-plan.jsonl
```

--------------------------------

### hf jobs uv run examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of using hf jobs uv run with various options: naming a job, detaching, selecting a flavor, installing packages, mounting volumes, and dry-run.

```bash
$ hf jobs uv run —name my-script my_script.py
```

```bash
$ hf jobs uv run —detach my_script.py
```

```bash
$ hf jobs uv run —flavor a10g-small ml_training.py
```

```bash
$ hf jobs uv run —with transformers train.py
```

```bash
$ hf jobs uv run -v hf://org/my-model:/data -v hf://buckets/org/b:/mnt script.py
```

```bash
$ hf jobs uv run —dry-run script.py
```

--------------------------------

### object_detection async example

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client

Performs object detection on an image using the default DETR model. Must be run in an async context. Requires PIL to be installed (pip install Pillow). The output is a list of ObjectDetectionOutputElement items.

```python
# Must be run in an async context
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()
>>> await client.object_detection("people.jpg")
[ObjectDetectionOutputElement(score=0.9486683011054993, label='person', box=ObjectDetectionBoundingBox(xmin=59, ymin=39, xmax=420, ymax=510)), ...]
```

--------------------------------

### Install and run hf-hello extension

Source: https://huggingface.co/docs/huggingface_hub/en/guides/cli-extensions

Commands to install and run the hf-hello extension. The output shows the expected result when no arguments are passed.

```bash
>>> hf extensions install <your-username>/hf-hello
>>> hf hello
Hello from hf-hello extension!
Arguments: []

```

--------------------------------

### hf extensions search output

Source: https://huggingface.co/docs/huggingface_hub/en/guides/cli-extensions

Example output of the `hf extensions search` command, listing GitHub repositories tagged with the `hf-extension` topic, sorted by stars. The INSTALLED column shows which extensions are already installed locally.

```bash
>>> hf extensions search
NAME   REPO                    STARS DESCRIPTION                         INSTALLED
------ ----------------------- ----- ----------------------------------- ---------
claude hanouticelina/hf-claude     2 Extension for `hf` CLI to launch... yes
agents hanouticelina/hf-agents       HF extension to run local coding...
```

--------------------------------

### Output of multiple endpoints setup

Source: https://huggingface.co/docs/huggingface_hub/en/guides/webhooks

Shows the expected output when the server starts, listing the two created endpoints: /webhooks/trigger_training and /webhooks/trigger_evaluation.

```text
(...)
Webhooks are correctly setup and ready to use:
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training
  - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation
```

--------------------------------

### hf sandbox cp examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of copying files to and from a sandbox using hf sandbox cp.

```console
$ hf sandbox cp data.csv <sandbox_id>:/data/data.csv
```

```console
$ hf sandbox cp <sandbox_id>:/app/result.json result.json
```

--------------------------------

### hf buckets sync examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of using `hf buckets sync` to upload, download, delete, filter, plan, apply, and dry-run syncs between local directories and buckets.

```console
$ hf buckets sync ./data hf://buckets/user/my-bucket
```

```console
$ hf buckets sync hf://buckets/user/my-bucket ./data
```

```console
$ hf buckets sync ./data hf://buckets/user/my-bucket —delete
```

```console
$ hf buckets sync hf://buckets/user/my-bucket ./data —include ”_.safetensors” —exclude ”_.tmp”
```

```console
$ hf buckets sync ./data hf://buckets/user/my-bucket —plan sync-plan.jsonl
```

```console
$ hf buckets sync —apply sync-plan.jsonl
```

```console
$ hf buckets sync ./data hf://buckets/user/my-bucket —dry-run
```

```console
$ hf buckets sync ./data hf://buckets/user/my-bucket —dry-run | jq .
```

--------------------------------

### Basic text_to_image example

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client

Generates an image from a text prompt using the default model and saves it as a PNG. Requires PIL (pip install Pillow).

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

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

>>> image = client.text_to_image(
...     "An astronaut riding a horse on the moon.",
...     negative_prompt="low resolution, blurry",
...     model="stabilityai/stable-diffusion-2-1",
... )
>>> image.save("better_astronaut.png")
```

--------------------------------

### hf sandbox pool create examples

Source: https://huggingface.co/docs/huggingface_hub/en/package_reference/cli

Examples of using hf sandbox pool create with different options.

```console
$ hf sandbox pool create
```

```console
$ hf sandbox pool create python:3.12 —flavor cpu-basic
```

```console
$ hf sandbox pool create —per-host 50 —idle-timeout 30m
```
Tokens:
Raw