{"id":8924,"library":"dapr","title":"Dapr Python SDK","description":"The Dapr Python SDK (version 1.17.4) is the official library for building distributed applications with Dapr building blocks in Python. Dapr provides a portable, event-driven, serverless runtime that simplifies microservices development across cloud and edge environments. The SDK allows interaction with Dapr's APIs for state management, pub/sub, service invocation, bindings, and more. Dapr generally releases minor updates every 6-13 weeks, with three recent minor versions typically supported concurrently.","status":"active","version":"1.17.4","language":"en","source_language":"en","source_url":"https://github.com/dapr/python-sdk","tags":["dapr","microservices","distributed systems","sdk","cloud-native","actors"],"install":[{"cmd":"pip install dapr","lang":"bash","label":"Stable release"},{"cmd":"pip install dapr-ext-grpc dapr-ext-fastapi dapr-ext-flask dapr-ext-workflow","lang":"bash","label":"Optional Extensions"}],"dependencies":[],"imports":[{"symbol":"DaprClient","correct":"from dapr.clients import DaprClient"},{"note":"Used for defining Dapr Virtual Actors.","symbol":"ActorInterface","correct":"from dapr.actor import ActorInterface"},{"note":"Essential for catching Dapr-specific client errors.","symbol":"DaprInternalError","correct":"from dapr.clients.exceptions import DaprInternalError"}],"quickstart":{"code":"import os\nfrom dapr.clients import DaprClient\n\nSTATE_STORE_NAME = os.environ.get('STATE_STORE_NAME', 'statestore')\n\ndef main():\n    with DaprClient() as client:\n        key = 'my_key'\n        value = 'my_value'\n\n        # Save state\n        print(f\"Saving state: key={key}, value={value}\")\n        client.save_state(\n            store_name=STATE_STORE_NAME,\n            key=key,\n            value=value\n        )\n        print(\"State saved successfully.\")\n\n        # Get state\n        print(f\"Getting state for key: {key}\")\n        response = client.get_state(\n            store_name=STATE_STORE_NAME,\n            key=key\n        )\n        retrieved_value = response.data.decode('utf-8')\n        print(f\"Retrieved state: value={retrieved_value}\")\n\n        assert retrieved_value == value\n        print(\"State retrieval verified.\")\n\nif __name__ == '__main__':\n    # Make sure a Dapr sidecar is running (e.g., `dapr run --app-id myapp --dapr-http-port 3500 --dapr-grpc-port 50001 python your_script.py`)\n    # and a state store component named 'statestore' is configured.\n    main()","lang":"python","description":"This quickstart demonstrates how to initialize the Dapr Python client and interact with the Dapr state management building block to save and retrieve a key-value pair. Ensure a Dapr sidecar is running and a state store component (e.g., 'statestore') is configured and accessible to your application."},"warnings":[{"fix":"Always check the SDK changelog and Dapr runtime release notes for breaking changes before upgrading. Test SDK upgrades in development environments first.","message":"Major versions of the Dapr Python SDK (e.g., 1.x to 2.x) may introduce breaking API changes, including method signature changes, module path renames, or response object field renames.","severity":"breaking","affected_versions":"All major versions"},{"fix":"When performing service invocation, prefer HTTP or gRPC proxying where applicable. Refer to the Dapr documentation for the recommended approach to gRPC communication between services.","message":"Dapr's gRPC service invocation is deprecated in favor of gRPC proxying. Direct gRPC invocation via the SDK may be removed in future releases.","severity":"deprecated","affected_versions":"1.x and later"},{"fix":"Remove explicit calls to `DaprClient().wait()`. The client will automatically perform a health check against the Dapr sidecar at initialization.","message":"The `DaprClient().wait()` method is deprecated. The automatic outbound health check covers this use case upon client initialization.","severity":"deprecated","affected_versions":"1.13.0 and later"},{"fix":"Consult the Dapr documentation for the SDK to runtime compatibility matrix. Pin your Dapr SDK version explicitly in your `requirements.txt` (e.g., `dapr==1.17.4`) and ensure your Dapr runtime is within the supported range.","message":"Dapr SDK versions must be compatible with the Dapr runtime version. Mismatched versions can lead to subtle failures or unexpected behavior due to API discrepancies.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Exercise caution when using Alpha or Preview features in production. Be prepared for rapid changes and frequent updates to your code when new Dapr releases become available. Monitor Dapr release notes closely for updates on these features.","message":"Alpha and Preview features in Dapr and its SDKs are subject to change between releases, potentially without strict deprecation cycles.","severity":"gotcha","affected_versions":"All versions with Alpha/Preview features"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the Dapr sidecar is properly launched alongside your application (e.g., using `dapr run`). Verify the Dapr HTTP and gRPC ports are correct and not blocked. Check Dapr sidecar logs for initialization issues.","cause":"The Dapr sidecar (`daprd`) is not running, not reachable, or has not fully initialized before the application attempts to connect. This can also manifest as `Connection refused` errors.","error":"grpc.RpcError: StatusCode.UNAVAILABLE: Dapr sidecar unavailable"},{"fix":"Verify that your component YAML files are correctly placed and configured. Ensure the `dapr run` command includes the `--resources-path` argument pointing to your components directory. Check the component's name in your code matches the component's `name` field in its YAML definition.","cause":"A Dapr component (e.g., state store, pub/sub broker) specified in your application or code is not correctly defined, accessible, or deployed. This could be due to a missing component YAML file, incorrect `resources-path` in `dapr run`, or namespace mismatch in Kubernetes.","error":"Error component X cannot be found"},{"fix":"Inspect the Dapr sidecar logs (enable debug logging for more details) and your application logs. The Dapr API response often includes an `errorCode` and `message` that provides specific context (e.g., `ERR_STATE_STORE_NOT_FOUND`, `ERR_PUBSUB_PUBLISH_MESSAGE`).","cause":"A generic Dapr API error, often indicating an issue with the underlying component (e.g., state store database down) or a misconfiguration within Dapr itself that prevents it from fulfilling the request.","error":"I'm getting 500 Error responses when calling Dapr"}]}