Install & Compatibility
Where this runs
tested against v0.15.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.910 runs
installs and imports cleanly · install 0.0s · import 0.923s · 63.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 6.4s · import 0.815s · 59MB
64MB installed
● package 64MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CerbosClient
✓ from cerbos.sdk.client import CerbosClient
AsyncCerbosClient
✓ from cerbos.sdk.client import AsyncCerbosClient
Use for asynchronous applications, `CerbosClient` is synchronous.
Principal
✓ from cerbos.sdk.model import Principal
Recommended for type-safe principal definitions, although dictionaries are also accepted by `is_allowed`.
Resource
✓ from cerbos.sdk.model import Resource
Recommended for type-safe resource definitions, although dictionaries are also accepted by `is_allowed`.
Attribute
✓ from cerbos.sdk.model import Attribute
Used for defining individual attributes, typically within Principal or Resource objects.
This quickstart demonstrates how to create a `CerbosClient`, define a `Principal` and `Resource`, and perform a basic `is_allowed` authorization check. It also shows a simple batch check using `client.check` and `client.check_input`. Ensure a Cerbos PDP instance is running at the specified address (defaulting to `localhost:3593`) for the example to connect successfully.
from cerbos.sdk.client import CerbosClient
from cerbos.sdk.model import Principal, Resource
import os
# Configure Cerbos PDP address (e.g., local server or Cerbos Cloud)
# For local development, Cerbos usually runs on localhost:3593
CERBOS_PDP_ADDR = os.environ.get('CERBOS_PDP_ADDR', 'localhost:3593')
def run_check():
client = CerbosClient(CERBOS_PDP_ADDR)
# Define the principal (user) making the request
principal = Principal(
id="john.doe",
roles=["employee"],
attributes={
"department": "marketing",
"geography": "EU"
}
)
# Define the resource being accessed
resource = Resource(
id="leave_request_123",
kind="leave_request",
attributes={
"owner": "john.doe",
"status": "pending",
"geography": "EU"
}
)
# Perform an authorization check
if client.is_allowed("view", principal, resource):
print(f"Principal '{principal.id}' IS ALLOWED to 'view' resource '{resource.id}'.")
else:
print(f"Principal '{principal.id}' IS NOT ALLOWED to 'view' resource '{resource.id}'.")
# Example of a batch check
# You can also use client.check(inputs) for multiple checks at once
check_result = client.check(
inputs=[
client.check_input("view", principal, resource),
client.check_input("edit", principal, resource)
]
)
print(f"\nBatch check results: {check_result.resource_instances['leave_request_123'].actions}")
if __name__ == '__main__':
print(f"Attempting to connect to Cerbos PDP at: {CERBOS_PDP_ADDR}")
try:
run_check()
except Exception as e:
print(f"An error occurred. Is the Cerbos PDP running at {CERBOS_PDP_ADDR}? Error: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cerbos.sdk'
The `cerbos` library is not installed or the Python environment is incorrect.
fixEnsure `cerbos` is installed in your active Python environment: `pip install cerbos`.
grpc.aio._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with: status = StatusCode.UNAVAILABLE, details = "Connect Failed", debug_error_string = "{"created":"@1678881234.567890","description":"Failed to connect to remote host: Connection refused","file":"src/core/lib/transport/error_utils.cc","file_line":166,"grpc_status":14}">
The Cerbos Policy Decision Point (PDP) server is not running or is inaccessible at the configured address and port.
fixStart your Cerbos PDP server. Verify that the `CERBOS_PDP_ADDR` environment variable or the address passed to `CerbosClient` (default `localhost:3593`) matches the PDP's listening address. Check firewall settings.
grpc.aio._channel._InactiveRpcError: <_InactiveRpcError of RPC that terminated with: status = StatusCode.FAILED_PRECONDITION, details = "policy compilation failed: ...", debug_error_string = "...">
The Cerbos PDP encountered an error during policy evaluation, typically due to malformed policies, invalid schema definitions, or issues with the request structure that violate policy constraints.
fixExamine the `details` field in the error message for specific policy compilation failures. Review your Cerbos policies (`.yaml` files) and schema definitions. Ensure your `Principal` and `Resource` inputs conform to any defined schemas.
AttributeError: 'dict' object has no attribute 'with_attributes'
You are attempting to use a method like `with_attributes()` (which belongs to `cerbos.sdk.model.Principal` or `Resource` objects) on a plain Python dictionary.
fixAlways instantiate `Principal` and `Resource` objects from `cerbos.sdk.model` when you intend to use their object-oriented methods. For example: `principal = Principal(id='user').with_attributes(...)`.
Upgrade
Version history
0.15.1latest on PyPI · released Jan 12, 2026
Audit
Dependencies
grpciorequiredRequired for gRPC communication with the Cerbos Policy Decision Point (PDP).
protobufrequiredRequired for serializing and deserializing data according to Protobuf definitions used by gRPC.