hf-gradio

0.3.0 · active · verified Tue Apr 14

hf-gradio is an extension of the Hugging Face CLI, designed to streamline interaction with Gradio Spaces and Apps. It provides command-line tools for tasks like running, deploying, and managing Gradio applications on the Hugging Face Hub, alongside a Python API that extends `gradio_client.Client` with Hugging Face integration. The current version is 0.3.0, and it generally follows the release cadence of Gradio and Hugging Face Hub libraries, with frequent updates during its early development phase.

Warnings

gotcha The `hf-gradio` library's primary interface is the `huggingface-cli gradio` command-line tool. While it offers a Python API via `hf_gradio.client.GradioClient`, most of its unique functionalities (like deploying, running, or managing spaces) are exposed through the CLI extension rather than direct Python functions.
Fix: Consult the official GitHub README for comprehensive CLI examples. Use `gradio_client.Client` directly if you only need programmatic interaction with a Gradio app without the specific Hugging Face Hub integration provided by `hf-gradio`'s client.
gotcha Interacting with private Gradio Spaces or performing authenticated operations (such as deploying new apps or managing existing ones) requires a valid Hugging Face API token. This token should be provided either via the `HF_TOKEN` environment variable or explicitly as the `hf_token` argument.
Fix: Set your Hugging Face token: `export HF_TOKEN='hf_YOUR_TOKEN'` (for CLI/environment) or pass `hf_token='hf_YOUR_TOKEN'` when initializing `GradioClient` or using relevant programmatic functions.
breaking As a relatively new library (v0.3.0), `hf-gradio` is under active development. Early minor versions (0.x.x) may introduce breaking changes to the Python API or CLI arguments as the project matures and stabilizes its public interfaces.
Fix: Always pin your `hf-gradio` version in `requirements.txt` (e.g., `hf-gradio==0.3.0`) and consult the GitHub releases and changelog before upgrading, especially across minor version bumps, to anticipate changes.

Install

pip install hf-gradio Install `hf-gradio`

Imports

GradioClient
```
from hf_gradio.client import GradioClient
```
Used for programmatic interaction with Gradio Spaces, extending `gradio_client.Client` with Hugging Face Hub integration.

Quickstart

Demonstrates connecting to a public Gradio Space using `hf_gradio.client.GradioClient` and making a simple prediction. It includes a placeholder for an optional Hugging Face token, which is crucial for private spaces or rate-limited public access.

import os
from hf_gradio.client import GradioClient

# Replace with your actual Hugging Face token if connecting to private spaces
# For public spaces, a token is often not strictly required, but good practice for rate limits.
hf_token = os.environ.get('HF_TOKEN', '')

try:
    # Connect to a public Gradio Space (e.g., 'gradio/hello_world')
    client = GradioClient(space_id="gradio/hello_world", hf_token=hf_token)
    print(f"Connected to space: {client.src}")

    # Make a prediction using the API name for the first function in the space
    # For gradio/hello_world, the default API name is usually '/predict'
    result = client.predict(
        name="Gradio User",
        api_name="/predict"
    )

    print(f"Prediction result: {result}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Make sure the Gradio Space ID is correct and accessible.")
    print("If it's a private space, ensure HF_TOKEN environment variable is set or passed correctly.")

view raw JSON →