Registry / ai-ml / hf-gradio

hf-gradio

JSON →
library0.4.1pypypiunverified

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.

pip install hf-gradio
INSTALL
IMPORT
SIG · HF-GRADIO
H
hf-gradio
ai-mlpythonv0.4.1
Install
4.7s avg
Import
Disk
59MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 4.85s
py 3.11
✓ —
✓ 5.03s
py 3.12
✓ —
✓ 4.53s
py 3.13
✓ —
✓ 4.53s
py 3.9
✕ build_error
✕ build_error
59MB installed
● package 59MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

GradioClient
from hf_gradio import GradioClient
from hf_gradio import GradioClient

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.")
hf-gradio --version
Debug
Known issues
gotchaThe `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.
affects: All versions
gotchaInteracting 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.
affects: All versions
breakingAs 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.
affects: 0.x.x versions
Upgrade
Version history
0.4.1latest on PyPI · released Apr 17, 2026
Audit
Dependencies
gradio-clientrequiredProvides core functionality for programmatic interaction with Gradio apps, extended by `hf-gradio`.
huggingface-hubrequiredEssential for authentication, managing, and interacting with the Hugging Face Hub and Spaces.
typerrequiredPowers the command-line interface (CLI) for `huggingface-cli gradio`.
richrequiredUsed for rich terminal output in the CLI tools.
Agent activity
40 hits · last 30 days
node
38
OpenAI (training)
1
Resources
hf-gradio — pip install hf-gradio · libregistry