{"id":1500,"library":"gradio-client","title":"Gradio Client","description":"Gradio Client is a Python library designed for programmatically interacting with deployed Gradio applications. It allows developers to make API calls to Gradio-hosted machine learning models or other Gradio apps without needing the UI. The current stable version is 2.4.0. It's actively developed as part of the broader Gradio ecosystem, with frequent updates corresponding to Gradio's release cycle.","status":"active","version":"2.4.0","language":"en","source_language":"en","source_url":"https://github.com/gradio-app/gradio/tree/main/client/python","tags":["AI","ML","client","Gradio","Hugging Face"],"install":[{"cmd":"pip install gradio-client","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for making HTTP requests to Gradio servers.","package":"httpx","optional":false},{"reason":"For interacting with Hugging Face Spaces and authentication.","package":"huggingface-hub","optional":false},{"reason":"Used for file system abstraction, particularly when handling remote files.","package":"fsspec","optional":false}],"imports":[{"note":"The Client class was moved to its own `gradio-client` package in Gradio v3.14. Direct import from `gradio` no longer works for newer versions.","wrong":"from gradio.client import Client","symbol":"Client","correct":"from gradio_client import Client"}],"quickstart":{"code":"import os\nfrom gradio_client import Client\n\n# Replace with your Gradio app URL or Hugging Face Space ID\n# For private Spaces, set the HF_TOKEN environment variable or pass hf_token directly.\nSPACE_URL = os.environ.get('GRADIO_SPACE_URL', 'https://hf.space/gradio/calculator')\nHF_TOKEN = os.environ.get('HF_TOKEN', '') # Optional: for private Hugging Face Spaces\n\nclient = Client(SPACE_URL, hf_token=HF_TOKEN)\n\n# Example for a simple calculator app with 'add' function taking two numbers\ntry:\n    # Use client.predict for synchronous calls\n    result = client.predict(2, 3, api_name='/add')\n    print(f\"Result of 2 + 3: {result}\")\n\n    # Use client.submit for asynchronous calls or streaming output (not shown here)\n    job = client.submit(10, 5, api_name='/subtract')\n    print(f\"Result of 10 - 5 (via job): {job.result()}\")\nexcept Exception as e:\n    print(f\"Error interacting with Gradio app: {e}\")\n    print(\"Please ensure the Gradio app is running and the API name is correct.\")\n","lang":"python","description":"This quickstart demonstrates how to instantiate a `Client` for a Gradio application and make synchronous API calls using `client.predict()` and `client.submit().result()`. It includes basic error handling and shows how to pass a Hugging Face token for private spaces using an environment variable."},"warnings":[{"fix":"Install `gradio-client` via `pip install gradio-client` and update your imports from `from gradio.client import Client` to `from gradio_client import Client`.","message":"The `gradio.client` module was deprecated and removed in Gradio v3.14. Functionality was moved to the separate `gradio-client` package. If you were using `gradio.client.Client` directly, you must now install `gradio-client` and import `Client` from there.","severity":"breaking","affected_versions":"Gradio >= 3.14, gradio-client >= 1.0.0"},{"fix":"For long-running tasks or when expecting streaming data, use `job = client.submit(...)` and then retrieve results via `job.result()` or `job.outputs()`. For real-time updates, you might need `job.listen()`.","message":"Distinction between `client.predict()` and `client.submit()`: `predict()` is a synchronous, blocking call that returns the result directly. `submit()` returns a `Job` object, allowing for asynchronous execution, polling for results, and handling streaming outputs. Using `predict()` for long-running tasks or when streaming is expected will block your program.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the local file path provided as input exists and is accessible. When processing file outputs, remember they are temporary. If you need to persist them, copy or move the file from the temporary path after the call returns.","message":"File inputs/outputs are handled automatically but can be unintuitive. When providing a local file path as input, `gradio-client` uploads it. When receiving a file output, `predict()` returns a temporary file path on the local machine.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pass your Hugging Face API token using the `hf_token` parameter when initializing `Client`, e.g., `Client('repo_id', hf_token='hf_xxxxxxxxxxxxxxxxxxxxx')`, or set the `HF_TOKEN` environment variable, which `gradio-client` will pick up automatically.","message":"Authentication for private Hugging Face Spaces requires an `hf_token`. Forgetting to provide this token will result in authentication errors when trying to access private models.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}