Install & Compatibility
Where this runs
tested against v12.4.5 · 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.920 runs
installs and imports cleanly · install 0.0s · import 1.849s · 44.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.1s · import 0.346s · 43MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ClarifaiChannel
✓ from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
Used to establish the gRPC communication channel with the Clarifai API.
V2Stub
✓ from clarifai_grpc.grpc.api import service_pb2_grpc
stub = service_pb2_grpc.V2Stub(...)
The primary interface for making API calls. Users often mistakenly try to import `V2Stub` directly or from an incorrect path.
resources_pb2
✓ from clarifai_grpc.grpc.api import resources_pb2
Contains definitions for various Clarifai resources like `Input`, `Concept`, `Model`, etc.
service_pb2
✓ from clarifai_grpc.grpc.api import service_pb2
Contains definitions for service requests and responses.
status_code_pb2
✓ from clarifai_grpc.grpc.api.status import status_code_pb2
Provides status codes for API responses, useful for error handling.
This quickstart demonstrates how to initialize the Clarifai gRPC client using a Personal Access Token (PAT) and make a prediction on an image URL. It retrieves the PAT and Application ID from environment variables, which is the recommended authentication method. Remember to replace 'YOUR_USER_ID' and 'YOUR_CLARIFAI_APP_ID' with your actual Clarifai credentials if not set as environment variables.
import os
from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2
# Your Clarifai PAT (Personal Access Token) and Application ID
CLARIFAI_PAT = os.environ.get('CLARIFAI_PAT', '')
CLARIFAI_APP_ID = os.environ.get('CLARIFAI_APP_ID', 'YOUR_CLARIFAI_APP_ID')
# Initialize the gRPC client
channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)
metadata = (('authorization', 'Key ' + CLARIFAI_PAT),)
userDataObject = resources_pb2.UserAppIDSet(user_id='YOUR_USER_ID', app_id=CLARIFAI_APP_ID)
# Example: Predict concepts in an image URL
image_url = 'https://samples.clarifai.com/metro-north.jpg'
post_model_outputs_response = stub.PostModelOutputs(
service_pb2.PostModelOutputsRequest(
# You can use your own model ID or a public one like 'general-image-recognition'
model_id='general-image-recognition',
user_app_id=userDataObject,
inputs=[
resources_pb2.Input(
data=resources_pb2.Data(
image=resources_pb2.Image(url=image_url)
)
)
]
),
metadata=metadata
)
if post_model_outputs_response.status.code != status_code_pb2.SUCCESS:
raise Exception(
f"Post model outputs failed, status: {post_model_outputs_response.status.description}"
)
# Print the results
print('Predicted concepts:')
for concept in post_model_outputs_response.outputs[0].data.concepts:
print(f"{concept.name}: {concept.value:.4f}")
Debug
Known issues
breakingThe `clarifai-grpc` library does not adhere to strict semantic versioning. The first two version numbers (X.Y) align with the backend API version, meaning even minor version changes can introduce breaking changes.fixAlways check the Clarifai API documentation and changelog for breaking changes when updating the library.
affects: All versions
breakingAs of June 11th, 2025, there are important changes to the use of PATs (Personal Access Tokens) and API keys, which may not be backward compatible.fixReview the official Clarifai documentation on 'Upcoming Platform Changes' for details and update your authentication logic accordingly before the specified date.
affects: >=12.0.0 (anticipated impact from June 2025)
gotchaWhen using PATs (Personal Access Tokens) for authentication, you must explicitly specify both your `user_id` and the `app_id` to which the request should be applied. App-specific API keys do not require this. PATs are also required for certain API operations like creating new applications.fixEnsure `resources_pb2.UserAppIDSet(user_id='YOUR_USER_ID', app_id='YOUR_APP_ID')` is correctly provided in your API requests when using a PAT.
affects: All versions
deprecatedThe `clarifai-python-utils` repository is deprecated. While `clarifai-grpc` remains available for granular API access, Clarifai encourages the use of the newer, object-oriented `clarifai-python` SDK (which wraps `clarifai-grpc`) for most use cases to simplify AI workflows.fixConsider migrating to the `clarifai` Python SDK (`pip install clarifai`) for an improved developer experience, or continue using `clarifai-grpc` for direct gRPC interaction.
affects: <12.0.0 (deprecation announced September 2023)
breakingFor applications created via the API without explicitly specifying a base workflow, the default changed from 'General' to 'Universal' on July 2nd, 2024. This affects the default behavior of newly created applications.fixManually specify your desired base workflow using an API parameter or through the UI if you do not wish to use the 'Universal' workflow.
affects: Applications created via API from '2024-07-02'
Errors
Common errors & fixes
Failed building wheel for grpcio
This error often occurs during installation because of issues compiling the `grpcio` dependency, frequently related to `setuptools` or other build tools.
fixUpgrade `setuptools` to a recent version before installing `clarifai-grpc`: `pip install --upgrade setuptools` and then `pip install clarifai-grpc`.
Request failed, status code: 11001
Status code 11001 (CONN_TOKEN_INVALID) indicates that the provided authentication token (API Key or Personal Access Token) is invalid or malformed. Other common authentication related codes include 11008 (CONN_KEY_INVALID) or 11009 (CONN_KEY_NOT_FOUND).
fixEnsure your Clarifai API Key or Personal Access Token (PAT) is correct, has the necessary permissions, and is properly included in the metadata for your gRPC requests. Double-check for typos or leading/trailing spaces. If using a PAT, ensure `user_app_id` is also correctly set.
gRPC failed to connect to all addresses
This error suggests a network connectivity issue between your client and the Clarifai gRPC servers, often due to SSL certificate problems (e.g., Let's Encrypt certificate expirations) or firewall restrictions.
fixTry upgrading your `grpcio` and `grpcio-tools` packages (`pip install --upgrade grpcio grpcio-tools`). If the problem persists, consider using the HTTPS+JSON channel as a workaround: `channel = ClarifaiChannel.get_json_channel()` instead of `ClarifaiChannel.get_grpc_channel()`.
Request failed, status code: 3
Status code 3 (INVALID_ARGUMENT) indicates that one or more arguments provided in your API request are invalid or malformed, regardless of the system's state.
fixCarefully review your request payload (e.g., input URLs, model IDs, user/app IDs, concept names) against the Clarifai API documentation to ensure all arguments are correctly formatted and valid. Log the full `response` object to inspect details in `response.status.details` or `response.status.description`.
ModuleNotFoundError: No module named 'clarifai_grpc.channel'
This error means that the `clarifai-grpc` library or its required submodules could not be found by Python, typically because the package was not installed, installed in a different environment, or there's a typo in the import statement.
fixEnsure `clarifai-grpc` is correctly installed in your active Python environment using `pip install clarifai-grpc`. Verify the import statement matches the official library structure: `from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel`.
Upgrade
Version history
12.4.5latest on PyPI · released May 29, 2026
Audit
Dependencies
protobufrequiredRequired for gRPC serialization; Clarifai requires protobuf>=3.20.3.