{"id":5956,"library":"hf-gradio","title":"hf-gradio","description":"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.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/gradio-app/hf-gradio#","tags":["gradio","huggingface","cli","spaces","machine learning","web app"],"install":[{"cmd":"pip install hf-gradio","lang":"bash","label":"Install `hf-gradio`"}],"dependencies":[{"reason":"Provides core functionality for programmatic interaction with Gradio apps, extended by `hf-gradio`.","package":"gradio-client"},{"reason":"Essential for authentication, managing, and interacting with the Hugging Face Hub and Spaces.","package":"huggingface-hub"},{"reason":"Powers the command-line interface (CLI) for `huggingface-cli gradio`.","package":"typer"},{"reason":"Used for rich terminal output in the CLI tools.","package":"rich"}],"imports":[{"note":"Used for programmatic interaction with Gradio Spaces, extending `gradio_client.Client` with Hugging Face Hub integration.","symbol":"GradioClient","correct":"from hf_gradio.client import GradioClient"}],"quickstart":{"code":"import os\nfrom hf_gradio.client import GradioClient\n\n# Replace with your actual Hugging Face token if connecting to private spaces\n# For public spaces, a token is often not strictly required, but good practice for rate limits.\nhf_token = os.environ.get('HF_TOKEN', '')\n\ntry:\n    # Connect to a public Gradio Space (e.g., 'gradio/hello_world')\n    client = GradioClient(space_id=\"gradio/hello_world\", hf_token=hf_token)\n    print(f\"Connected to space: {client.src}\")\n\n    # Make a prediction using the API name for the first function in the space\n    # For gradio/hello_world, the default API name is usually '/predict'\n    result = client.predict(\n        name=\"Gradio User\",\n        api_name=\"/predict\"\n    )\n\n    print(f\"Prediction result: {result}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Make sure the Gradio Space ID is correct and accessible.\")\n    print(\"If it's a private space, ensure HF_TOKEN environment variable is set or passed correctly.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.x.x versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}