Install & Compatibility
Where this runs
tested against v2.6.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.970s · 47.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.2s · import 0.864s · 48MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from gradio_client import Client
✗ from gradio.client import Client
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.
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.
import os
from gradio_client import Client
# Replace with your Gradio app URL or Hugging Face Space ID
# For private Spaces, set the HF_TOKEN environment variable or pass hf_token directly.
SPACE_URL = os.environ.get('GRADIO_SPACE_URL', 'https://hf.space/gradio/calculator')
HF_TOKEN = os.environ.get('HF_TOKEN', '') # Optional: for private Hugging Face Spaces
client = Client(SPACE_URL, hf_token=HF_TOKEN)
# Example for a simple calculator app with 'add' function taking two numbers
try:
# Use client.predict for synchronous calls
result = client.predict(2, 3, api_name='/add')
print(f"Result of 2 + 3: {result}")
# Use client.submit for asynchronous calls or streaming output (not shown here)
job = client.submit(10, 5, api_name='/subtract')
print(f"Result of 10 - 5 (via job): {job.result()}")
except Exception as e:
print(f"Error interacting with Gradio app: {e}")
print("Please ensure the Gradio app is running and the API name is correct.")
Debug
Known issues
breakingThe `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.fixInstall `gradio-client` via `pip install gradio-client` and update your imports from `from gradio.client import Client` to `from gradio_client import Client`.
affects: Gradio >= 3.14, gradio-client >= 1.0.0
gotchaDistinction 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.fixFor 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()`.
affects: All versions
gotchaFile 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.fixEnsure 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.
affects: All versions
gotchaAuthentication 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.fixPass 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. affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gradio_client.serializing'
This error typically occurs due to an incompatibility between installed versions of `gradio` and `gradio-client`, where a `gradio` version expects a module (`gradio_client.serializing`) that has been removed in `gradio-client 2.x` versions.
fixEnsure compatible versions of `gradio` and `gradio-client` are installed, or upgrade both to their latest stable versions (`pip install --upgrade gradio gradio-client`) to resolve dependency conflicts.
ModuleNotFoundError: No module named 'gradio_client'
The `gradio_client` library is not installed in the current Python environment, or the Python interpreter being used does not have access to the installed library.
fixInstall the library using `pip install gradio-client`. If already installed, verify that you are running your script with the correct Python interpreter associated with the environment where `gradio-client` was installed.
AttributeError: 'Client' object has no attribute 'src_prefixed'
This `AttributeError` has been reported in `gradio-client` when attempting to connect to Gradio Spaces or applications multiple times, or due to internal state issues within the `Client` object, particularly when handling connection retries or specific server responses. It was often a bug in older versions.
fixEnsure `gradio-client` is updated to the latest version (`pip install --upgrade gradio-client`). If the issue persists, try re-initializing the `Client` object for each new connection attempt to ensure a clean state.
SSLError: CERTIFICATE_VERIFY_FAILED
This error occurs when the `gradio-client` attempts to connect to a Gradio application over HTTPS (especially a locally served one) that uses a self-signed or untrusted SSL certificate, which the client cannot verify.
fixWhen connecting to local or untrusted HTTPS endpoints, pass `ssl_verify=False` to the `Client()` constructor (e.g., `client = Client('https://your-app.com', ssl_verify=False)`). Use this with caution as it disables SSL verification. For public Hugging Face Spaces, ensure the URL is correct. ValueError: None (when calling client.predict() or client.submit())
This error often indicates that the `predict` or `submit` method received `None` as an input for a parameter that expects a non-`None` value, or that the remote Gradio application itself returned `None` unexpectedly due to an issue in its backend logic or input handling.
fixCarefully check the arguments passed to `client.predict()` or `client.submit()` to ensure all required inputs have appropriate, non-`None` values. Additionally, inspect the Gradio application's API documentation or source to understand expected input types and debug the app's backend if the issue originates there.
Upgrade
Version history
2.6.1latest on PyPI · released Aug 24, 2026
Audit
Dependencies
httpxrequiredUsed for making HTTP requests to Gradio servers.
huggingface-hubrequiredFor interacting with Hugging Face Spaces and authentication.
fsspecrequiredUsed for file system abstraction, particularly when handling remote files.