Install & Compatibility
Where this runs
tested against v0.0.62 · 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 0.856s · 231.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 16.3s · import 0.092s · 225MB
234MB installed
● package 234MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Image
✓ from clarifai_grpc.grpc.api.resources_pb2 import Image
✗ from clarifai_protocol.grpc.api.resources_pb2 import Image
The generated Python code places the imports under `clarifai_grpc`, not `clarifai_protocol`.
V2Stub
✓ from clarifai_grpc.grpc.api.service_pb2_grpc import V2Stub
✗ from clarifai_protocol.grpc.api.service_pb2_grpc import V2Stub
Service stubs are also found under the `clarifai_grpc` namespace.
UserAppIDSet
✓ from clarifai_grpc.grpc.api.resources_pb2 import UserAppIDSet
Commonly used for authentication and context in gRPC requests.
This quickstart demonstrates how to import and instantiate core Protocol Buffer messages like `Image` and `UserAppIDSet`, and how to access a gRPC service stub like `V2Stub`. While it shows creating a request message, actual API interaction requires setting up a gRPC channel and credentials, which falls outside the scope of `clarifai-protocol` itself, but relies on its definitions.
from clarifai_grpc.grpc.api.resources_pb2 import Image, UserAppIDSet
from clarifai_grpc.grpc.api.service_pb2 import PostModelOutputsRequest
from clarifai_grpc.grpc.api.service_pb2_grpc import V2Stub
import grpc
import os
# This library primarily provides the definitions. Actual API calls require grpcio and a channel.
# Example: Instantiate a protobuf message
image_message = Image(url="https://samples.clarifai.com/face-det.jpg")
print(f"Created Image message with URL: {image_message.url}")
# Example: Create a stub (though actual usage requires a gRPC channel and credentials)
# For demonstration purposes, we'll just show the import and instantiation of the stub class.
# In a real scenario, you'd pass a channel: V2Stub(grpc.insecure_channel('api.clarifai.com:443'))
try:
channel = grpc.insecure_channel('api.clarifai.com:443') # Using a dummy channel for concept
stub = V2Stub(channel)
print(f"Successfully created a V2Stub instance.")
channel.close()
except Exception as e:
print(f"Could not create a real gRPC channel for demonstration: {e}")
print("Stub instantiation shown for clarity, but requires a functional gRPC channel.")
# Example: A request message, typically constructed using these resources
request = PostModelOutputsRequest(
user_app_id=UserAppIDSet(user_id=os.environ.get('CLARIFAI_USER_ID', ''), app_id=os.environ.get('CLARIFAI_APP_ID', '')),
model_id="my-model",
inputs=[] # inputs would go here
)
print(f"Created PostModelOutputsRequest for model: {request.model_id}")
Debug
Known issues
breakingChanges to the underlying Clarifai Protocol Buffer (.proto) definitions directly lead to breaking changes in the generated Python classes (e.g., field renames, type changes, field removals).fixAlways check the release notes for `clarifai-protocol` and update your code to match the new field names, types, or message structures. Re-generating your own code from `.proto` files if you maintain a fork might also be necessary.
affects: All versions, as it reflects the protocol. Major changes often correspond to significant version bumps of clarifai-protocol.
gotchaThe `clarifai-protocol` library is NOT the high-level Clarifai Python Client Library (which is typically `clarifai` or `clarifai-client`). This library provides the low-level gRPC/Protobuf definitions.fixIf you intend to use a high-level SDK for interacting with Clarifai APIs, you likely want `pip install clarifai`. Use `clarifai-protocol` when building custom gRPC services, runners, or directly manipulating Protobuf messages for advanced integrations.
affects: All versions.
gotchaConfusing `*_pb2` and `*_pb2_grpc` modules. `_pb2` modules contain the generated Protobuf message classes (data structures), while `_pb2_grpc` modules contain the generated gRPC service stubs (client interfaces) and servicer classes (server interfaces).fixRemember that `resources_pb2` is for messages like `Image` or `Concept`, while `service_pb2_grpc` is for stubs like `V2Stub` or `PublicServiceStub`. Import carefully based on whether you need a data structure or a service interface.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'clarifai_grpc.grpc.api.resources_pb2'
The `clarifai-protocol` library is not installed, or the import path is incorrect.
fixEnsure the library is installed with `pip install clarifai-protocol`. Verify that the import path is `from clarifai_grpc.grpc.api...` and not `from clarifai_protocol.grpc.api...`.
AttributeError: 'Image' object has no attribute 'image_url'
A Protobuf message field has been renamed or removed in a newer version of the protocol definition.
fixConsult the `clarifai-protocol` documentation or the `.proto` files in the GitHub repository for the correct field name. For example, `image_url` might have been changed to simply `url`.
Upgrade
Version history
0.0.62latest on PyPI · released May 5, 2026
Audit
Dependencies
grpciorequiredRequired for gRPC client/server functionality, which is the underlying communication protocol.
grpcio-toolsrequiredProvides tools for working with gRPC, often used for code generation but also as a runtime dependency.
protobufrequiredGoogle's Protocol Buffers library, essential for serializing and deserializing the structured data messages.