{"id":1031,"library":"temporalio","title":"Temporal.io Python SDK","description":"The Temporal.io Python SDK (current version 1.24.0) provides a framework for authoring durable workflows and activities using the Python programming language. It enables developers to build resilient, scalable, and fault-tolerant applications that can execute long-running business logic reliably. The library maintains a regular release cadence, often with monthly or bi-monthly updates, introducing new features, improvements, and bug fixes.","status":"active","version":"1.24.0","language":"python","source_language":"en","source_url":"https://github.com/temporalio/sdk-python","tags":["workflow orchestration","distributed systems","microservices","fault tolerance","sdk","long-running processes","asynchronous"],"install":[{"cmd":"pip install temporalio","lang":"bash","label":"Install the latest version"}],"dependencies":[{"reason":"Runtime requirement","package":"Python","version":">=3.10"},{"reason":"Optional integration for OpenAI Agent SDK","package":"openai-agents","optional":true},{"reason":"Optional integration for Google ADK agents","package":"google-adk","optional":true},{"reason":"Optional integration for OpenTelemetry tracing","package":"opentelemetry","optional":true},{"reason":"Optional support for Pydantic models in data conversion","package":"pydantic","optional":true},{"reason":"Optional gRPC dependency for advanced use cases","package":"grpc","optional":true}],"imports":[{"note":"Used to connect to a Temporal Cluster and interact with workflows (start, signal, query).","symbol":"Client","correct":"from temporalio.client import Client"},{"note":"Used to host workflow and activity implementations and poll task queues.","symbol":"Worker","correct":"from temporalio.worker import Worker"},{"note":"Provides decorators like `@workflow.defn` for defining workflows and functions like `workflow.execute_activity` for orchestrating activities.","symbol":"workflow","correct":"from temporalio import workflow"},{"note":"Provides decorators like `@activity.defn` for defining activities.","symbol":"activity","correct":"from temporalio import activity"},{"note":"Crucial for importing activity modules into workflow files when those activity modules have non-deterministic or non-standard library imports, to prevent sandbox errors.","symbol":"workflow.unsafe.imports_passed_through","correct":"from temporalio import workflow\nwith workflow.unsafe.imports_passed_through():\n    from my_app import my_activity_module"}],"quickstart":{"code":"import asyncio\nfrom datetime import timedelta\nfrom temporalio.client import Client\nfrom temporalio.worker import Worker\nfrom temporalio import activity, workflow\n\n# Define an activity\n@activity.defn\nasync def say_hello(name: str) -> str:\n    return f\"Hello, {name}!\"\n\n# Define a workflow\n@workflow.defn\nclass GreetingWorkflow:\n    @workflow.run\n    async def run(self, name: str) -> str:\n        return await workflow.execute_activity(\n            say_hello,\n            name,\n            schedule_to_close_timeout=timedelta(seconds=5),\n        )\n\nasync def main():\n    # Connect to Temporal server (default to localhost:7233)\n    # Use os.environ.get('TEMPORAL_HOST_PORT', 'localhost:7233') for dynamic connection\n    client = await Client.connect(os.environ.get('TEMPORAL_HOST_PORT', 'localhost:7233'))\n\n    # Run a worker\n    task_queue_name = \"my-task-queue\"\n    worker = Worker(\n        client,\n        task_queue=task_queue_name,\n        workflows=[GreetingWorkflow],\n        activities=[say_hello],\n    )\n    # Start worker in background\n    worker_task = asyncio.create_task(worker.run())\n    print(f\"Worker started on task queue '{task_queue_name}'...\")\n\n    # Start a workflow execution\n    result = await client.execute_workflow(\n        GreetingWorkflow.run,\n        \"Temporal\",\n        id=\"greeting-workflow-id\",\n        task_queue=task_queue_name,\n    )\n    print(f\"Workflow result: {result}\") # Expected: \"Hello, Temporal!\"\n\n    # Clean up worker\n    worker_task.cancel()\n    await worker_task\n\nif __name__ == \"__main__\":\n    import os\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to define an activity and a workflow, configure and start a Temporal worker to process tasks, and execute a workflow. It connects to a local Temporal server (defaulting to `localhost:7233`) and includes `os.environ.get` for flexible configuration."},"warnings":[{"fix":"Upgrade Python environment to 3.10 or a later supported version.","message":"Python 3.9 support was removed in version 1.19.0 as it reached End-of-Life. Users on Python 3.9 must upgrade to Python 3.10 or newer.","severity":"breaking","affected_versions":">=1.19.0"},{"fix":"Adjust code that manually accesses `activity.Info` fields to handle potential `None` values. Refactor any custom `BaseWorkflowSerializationContext` subclasses.","message":"In version 1.23.0, fields `workflow_id`, `workflow_namespace`, `workflow_run_id`, and `workflow_type` within `activity.Info` were made optional. Additionally, `converter.BaseWorkflowSerializationContext` was removed.","severity":"breaking","affected_versions":">=1.23.0"},{"fix":"Review and update OpenTelemetry tracing configurations if using OpenAI Agents with custom instrumentation. Leverage the GA features of Nexus and OpenAI Agents.","message":"Version 1.24.0 introduces general availability for Nexus and OpenAI Agents SDK Integration. It also includes new OpenTelemetry integration for OpenAI Agents, which may cause conflicts or require adjustments for existing custom OpenTelemetry setups.","severity":"breaking","affected_versions":">=1.24.0"},{"fix":"If you wish to use an `api_key` without TLS, explicitly pass `tls=False` to `Client.connect`.","message":"Beginning with version 1.21.0, providing an `api_key` to `Client.connect` automatically enables TLS.","severity":"gotcha","affected_versions":">=1.21.0"},{"fix":"For modules needed only by activities, import them within the activity function, or use `with workflow.unsafe.imports_passed_through(): import my_module` when importing them into workflow files. For performance, pass through any side-effect-free third-party libraries explicitly.","message":"The Workflow Sandbox isolates workflow code to ensure determinism. Importing non-standard library or non-`temporalio` modules directly into workflow files can lead to `RestrictedWorkflowAccessError` or non-determinism.","severity":"gotcha","affected_versions":"All versions with sandbox enabled (default)"},{"fix":"On Alpine Linux, ensure `build-base`, `gcc`, `g++`, and `rustup` (with the `x86_64-unknown-linux-musl` target) are installed in the build environment. For simpler deployments, consider using a glibc-based Python image (e.g., Debian-based) where pre-built `temporalio` wheels are more commonly available.","message":"Installing `temporalio` on Alpine Linux (especially with newer Python versions for which pre-built wheels may not exist) can fail due to missing build dependencies like `libgcc_s.so.1` or incompatible Rust compilation. Alpine's musl libc often requires specific system packages or a different Rust target to successfully compile native extensions.","severity":"breaking","affected_versions":"All versions when attempting to build from source on Alpine Linux without necessary system dependencies."}],"env_vars":null,"last_verified":"2026-05-12T22:49:09.622Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Ensure the Temporal server is running and confirm the `target_host` (e.g., `localhost:7233`) used in `Client.connect()` matches the server's address and port.","cause":"The Temporal client cannot establish a connection with the Temporal server, usually because the server is not running or is unreachable at the specified address.","error":"grpc._channel._MultiThreadedRendezvous: <_MultiThreadedRendezvous of RPC that terminated with: status = StatusCode.UNAVAILABLE"},{"fix":"Add the workflow class to the worker's `workflows` list and ensure the worker's `task_queue` argument matches the task queue specified when starting the workflow. Example: `Worker(client, task_queue='my-task-queue', workflows=[MyWorkflow])`.","cause":"The worker instance has not been configured to register the workflow class, or the task queue used to start the workflow does not match the worker's task queue.","error":"ApplicationError: type='temporal.workflow.NotFound', message='Workflow with name \"MyWorkflow\" is not registered on the worker.'"},{"fix":"Replace non-Temporal `await` calls (e.g., `await asyncio.sleep()`, `await aiohttp.get()`) with their deterministic Temporal counterparts (e.g., `await workflow.sleep()`) or encapsulate the non-deterministic logic within a Temporal Activity.","cause":"Temporal workflows require deterministic execution and cannot directly await arbitrary Python `asyncio` futures or blocking calls; they must use Temporal's specific asynchronous primitives or delegate to activities.","error":"RuntimeError: Workflow must not 'await' non-Temporal futures. Instead, use 'temporalio.workflow.asyncio.sleep', 'temporalio.workflow.asyncio.wait', etc."},{"fix":"Install the library using pip: `pip install temporalio`.","cause":"The `temporalio` Python SDK library has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'temporalio'"}],"ecosystem":"pypi","meta_description":null,"install_score":50,"install_tag":"draft","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.27.0","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"draft","tag_description":"notable install failures or slow imports","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3,"import_time_s":0.43,"mem_mb":13.7,"disk_size":"75M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":13.6,"disk_size":"73M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.9,"import_time_s":1.08,"mem_mb":14.7,"disk_size":"78M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.07,"mem_mb":14.6,"disk_size":"75M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.6,"import_time_s":1.25,"mem_mb":14.8,"disk_size":"70M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.31,"mem_mb":14.7,"disk_size":"67M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.9,"import_time_s":1.17,"mem_mb":15.6,"disk_size":"69M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.24,"mem_mb":15.4,"disk_size":"67M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":"build_error","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.4,"import_time_s":0.41,"mem_mb":12.7,"disk_size":"67M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.47,"mem_mb":12.7,"disk_size":"67M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}