Description
 [](https://pypi.org/project/temporalio) [](https://pypi.org/project/temporalio) [](LICENSE) **📣 News: Integration between OpenAI Agents SDK and Temporal is now in public preview. [Learn more](temporalio/contrib/openai_agents/README.md).** [Temporal](https://temporal.io/) is a distributed, scalable, durable, and highly available orchestration engine used to execute asynchronous, long-running business logic in a scalable and resilient way. "Temporal Python SDK" is the framework for authoring workflows and activities using the Python programming language. Also see: * [Application Development Guide](https://docs.temporal.io/application-development?lang=python) - Once you've tried our [Quick Start](#quick-start), check out our guide on how to use Temporal in your Python applications, including information around Temporal core concepts. * [Python Code Samples](https://github.com/temporalio/samples-python) * [API Documentation](https://python.temporal.io) - Complete Temporal Python SDK Package reference. In addition to features common across all Temporal SDKs, the Python SDK also has the following interesting features: **Type Safe** This library uses the latest typing and MyPy support with generics to ensure all calls can be typed. For example, starting a workflow with an `int` parameter when it accepts a `str` parameter would cause MyPy to fail. **Different Activity Types** The activity worker has been developed to work with `async def`, threaded, and multiprocess activities. Threaded activities are the initial recommendation, and further guidance can be found in [the docs](https://docs.temporal.io/develop/python/python-sdk-sync-vs-async). **Custom `asyncio` Event Loop** The workflow implementation basically turns `async def` functions into workflows backed by a distributed, fault-tolerant event loop. This means task management, sleep, cancellation, etc have all been developed to seamlessly integrate with `asyncio` concepts. See the [blog post](https://temporal.io/blog/durable-distributed-asyncio-event-loop) introducing the Python SDK for an informal introduction to the features and their implementation. --- <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> **Contents** - [Quick Start](#quick-start) - [Installation](#installation) - [Implementing a Workflow](#implementing-a-workflow) - [Running a Workflow](#running-a-workflow) - [Next Steps](#next-steps) - [Usage](#usage) - [Client](#client) - [Data Conversion](#data-conversion) - [Pydantic Support](#pydantic-support) - [Custom Type Data Conversion](#custom-type-data-conversion) - [External Storage](#external-storage) - [Driver Selection](#driver-selection) - [Built-in Drivers](#built-in-drivers) - [Custom Drivers](#custom-drivers) - [Workers](#workers) - [Workflows](#workflows) - [Definition](#definition) - [Running](#running) - [Invoking Activities](#invoking-activities) - [Invoking Child Workflows](#invoking-child-workflows) - [Timers](#timers) - [Conditions](#conditions) - [Asyncio and Determinism](#asyncio-and-determinism) - [Asyncio Cancellation](#asyncio-cancellation) - [Workflow Utilities](#workflow-utilities) - [Exceptions](#exceptions) - [Signal and update handlers](#signal-and-update-handlers) - [External Workflows](#external-workflows) - [Testing](#testing) - [Automatic Time Skipping](#automatic-time-skipping) - [Manual Time Skipping](#manual-time-skipping) - [Mocking Activities](#mocking-activities) - [Workflow Sandbox](#workflow-sandbox) - [How the Sandbox Works](#how-the-sandbox-works) - [Avoiding the Sandbox](#avoiding-the-sandbox) - [Customizing the Sandbox](#customizing-the-sandbox) - [Passthrough Modules](#passthrough-modules) - [Invalid Module Members](#invalid-module-members) - [Known Sandbox Issues](#known-sandbox-issues) - [Global Import/Builtins](#global-importbuiltins) - [Sandbox is not Secure](#sandbox-is-not-secure) - [Sandbox Performance](#sandbox-performance) - [Extending Restricted Classes](#extending-restricted-classes) - [Certain Standard Library Calls on Restricted Objects](#certain-standard-library-calls-on-restricted-objects) - [is_subclass of ABC-based Restricted Classes](#is_subclass-of-abc-based-restricted-classes) - [Activities](#activities) - [Definition](#definition-1) - [Types of Activities](#types-o
Release History
| Version | Changes | Urgency | Date |
|---|---|---|---|
| 1.26.0 | Imported from PyPI (1.26.0) | Low | 4/21/2026 |
| 1.25.0 | ## Pre-release Features ### Serverless Lambda Workers This release introduces a [package](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/aws/lambda_worker) which can be used together with upcoming changes to the Temporal server & cloud which allow you to run your worker in an AWS Lambda function which the server will invoke as-needed to process Workflow, Activity, and Nexus tasks - allowing you to do away with some of the operational burden of running a fleet of worker | Medium | 4/8/2026 |
| 1.24.0 | ## General Availability - Nexus is now generally available and no longer experimental - OpenAI Agents SDK Integration is now generally available and no longer experimental ## Pre-release - New Integration with the Google ADK for running ADK agents in Temporal Workflows. https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/google_adk_agents ## Breaking Changes ### :boom: Add OpenTelemetry integration for OpenAI AgentsOpenAI/otel in https://github.com/temporalio/sd | Medium | 3/23/2026 |
| 1.23.0 | ## :boom: Breaking Changes ### 💥 Experimental standalone activity support in https://github.com/temporalio/sdk-python/pull/1307 - `activity.Info` modified to make `workflow_id`, `workflow_namespace`, `workflow_run_id`, and `workflow_type` optional - 💥 SLIGHT BREAKING CHANGE for those manually expecting non-None fields or manually creating the info for tests - `converter.BaseWorkflowSerializationContext` intermediate base class removed - 💥 SLIGHT BREAKING CHANGE for those that may hav | Low | 2/18/2026 |
| 1.22.0 | ## Highlights * Deployment-based Worker Versioning APIs are in General Availability. * Environment Configuration is in General Availability. ## What's Changed * Adds basedpyright support to `poe lint` by @tconley1428 in https://github.com/temporalio/sdk-python/pull/1240 * Remove stdlib_module_names test that is no longer relevant by @VegetarianOrc in https://github.com/temporalio/sdk-python/pull/1259 * Update sdk-core to incorporate 1.60.0 api release by @jmaeagle99 in https://github.com | Low | 2/3/2026 |
| 1.21.1 | [PyPI](https://pypi.org/project/temporalio/) ## Bug Fixes * Dynamic handlers now support `typing.Sequence` and `collections.abc.Sequence` for their third argument. * Add compatibility with OpenAI Agents SDK 0.6.4. ## Specific Changes 2025-12-19 - 772050e - Add backward compatibility for dynamic handler signatures (#1258) 2025-12-19 - f0bd341 - OpenAI - Fix generics is instance (#1261) | Low | 12/19/2025 |
| 1.21.0 | [PyPI](https://pypi.org/project/temporalio/) ## TLS Automatically Enabled When API Key Provided When creating a `Client`, specifying the `api_key` option will now automatically enable TLS. Users that wish to use an API Key without TLS enabled must explicitly pass `tls=False` when creating their client. See [`Client.connect`](https://python.temporal.io/temporalio.client.Client.html#connect) for a detailed description of configuration options and behavior. ## Highlights * Core was up | Low | 12/18/2025 |
| 1.20.0 | [PyPI](https://pypi.org/project/temporalio/) ## Worker Heartbeating (Public Preview) This release adds a new feature called Worker Heartbeating. This feature spins up a single nexus-only worker per Client/Namespace in the background and periodically sends some basic metrics over to server for all of the workers registered on the same Client/Namespace. Server version [1.29.1](https://github.com/temporalio/temporal/releases/tag/v1.29.1) and newer supports this feature. This feature will b | Low | 11/25/2025 |
| 1.19.0 | ## Sandbox Importing Changes Modules imported after workflows have been loaded into the sandbox now produce a warning message by default. See the [Import Notification Policy](https://docs.temporal.io/develop/python/python-sdk-sandbox#import-notification-policy) docs for more info and customization options. ## OpenAI Agents Changes - Add new upper bound of version `0.5.0` for `openai-agents` ## Breaking Changes - Python 3.9 support has been removed now that it has reached end of li | Low | 11/13/2025 |
| 1.18.2 | [PyPI](https://pypi.org/project/temporalio/) ## Bug fixes - Ensure `cause` fields of `Failure` protos are encoded with user codecs. ## Specific Changes 2025-10-27 - e4969c05 - Adds proper failure decoding in workflow activation (#1192) **Full Changelog**: https://github.com/temporalio/sdk-python/compare/1.18.1...1.18.2 | Low | 10/27/2025 |
| 1.14.2 | [PyPI](https://pypi.org/project/temporalio/) ## Bug fixes - Pin `nexus-rpc` version to prevent accidental upgrade to a breaking version. ## Specific Changes 2025-10-23 - 988ad10 - Lock nexus-rpc to 1.1.0 **Full Changelog**: https://github.com/temporalio/sdk-python/compare/1.14.1...1.14.2 | Low | 10/23/2025 |
| 1.18.1 | [PyPI](https://pypi.org/project/temporalio/) ## Bug fixes - Search attributes on child workflows would fail when using a payload codec - Looping agent handoffs would try to use the original model outside an activity ## Specific Changes 2025-09-24 - 2f04a166 - Fix flaky test: test_workflow_return_is_honored_when_it_precedes_signal_completion_command (#1115) 2025-09-24 - 6dd59dd3 - Fix flaky test: test_workflow_patch_memoized (#1114) 2025-09-25 - fd51efa0 - Fix model replacement on lo | Low | 9/30/2025 |
| 1.18.0 | [PyPI](https://pypi.org/project/temporalio/) ## OpenAI Agents Changes - Support and new lower bound of version `0.3.0` for `openai-agents` - Workflow failure exceptions will now correctly fail the workflow from inside the `Runner` - Expanded MCP support ### Breaking Changes - The `encode_failure` method on `PayloadConverter` is no longer called in all cases it once was, using `encode_payload` instead. This only affects custom `PayloadConverter` implementations which overload `encode_fa | Low | 9/19/2025 |
| 1.17.0 | [PyPI](https://pypi.org/project/temporalio/) ## Nexus features - Nexus operation handlers can now use `id_conflict_policy=WorkflowIDConflictPolicy.USE_EXISTING` so that multiple callers "attach" to the same workflow. - Correct handling of `WorkflowAlreadyStartedError` ## Specific Changes 2025-08-25 - a9c71aa - Support multiple nexus callers attaching to same workflow (#1051) 2025-08-26 - 2affa25 - Python Nexus convert workflow start errors to Nexus errors (#1052) 2025-08-27 - 229fe37 | Low | 9/3/2025 |
| 1.16.0 | [PyPI](https://pypi.org/project/temporalio/) ## Task Queue Fairness (Pre-release) This release adds support for Task Queue Fairness. Fairness is a new feature of Temporal's task queues that allows for more control over the order that tasks are dispatched from a backlog. It's intended to address common situations like multi-tenant applications and reserved capacity bands. ## Nexus cancellation types (Pre-release) A cancellation type can now be set when starting a nexus operation. This | Low | 8/21/2025 |
| 1.15.0 | [PyPI](https://pypi.org/project/temporalio/) - Plugin support - Plugins are a new way of providing easy configuration of workers and clients - Ongoing development of OpenAI Agents Integration ### 💥 Breaking Changes - OpenAI Agents integration is now intended to be used through `OpenAIAgentsPlugin`, the previous method of configuring with `set_open_ai_agent_temporal_overrides` is no longer exported. - OpenAI Agents integration tracing now uses a separate random generator for uuids. If a | Low | 7/29/2025 |
| 1.14.1 | **❗UPDATE: Please update to latest release: the nexus-rpc version is not pinned in this release. This could cause errors on future nexus-rpc releases.** [PyPI](https://pypi.org/project/temporalio/) - Fixes a bug related to event links in Nexus Pre-release that resulted in 500 errors in web UI (#953) - The OpenAI Agents Integration module layout has changed, requiring different import paths in user code. All needed types are available off `temporalio.contrib.openai_agents` or `temporalio | Low | 7/10/2025 |
| 1.14.0 | **❗UPDATE: Please update to latest release: the nexus-rpc version is not pinned in this release. This could cause errors on future nexus-rpc releases.** [PyPI](https://pypi.org/project/temporalio/) ## Highlights - Experimental Nexus support (#813) The SDK now has experimental support for defining Nexus operations, running a Nexus worker, and calling Nexus operations cross-namespace from a workflow. See [README.md#nexus](https://github.com/temporalio/sdk-python/blob/main/README.md#nex | Low | 7/8/2025 |
| 1.13.0 | [PyPI](https://pypi.org/project/temporalio/) ## Highlights - Upgrading `pyo3` to `0.25` in preparation for python `3.14` support - Experimental integration with OpenAI Agents SDK ## Specific Changes 2025-06-02 - 520aefd - Swallowed cancellation (#879) 2025-06-05 - 316a528 - Handle case where in_workflow is called in a synchronous activity (#884) 2025-06-05 - 785aca6 - Add handling for datetimes to the default Json Converter (#872) 2025-06-05 - ee6f8d7 - Instantiate interceptors lat | Low | 6/20/2025 |
| 1.12.0 | [PyPI](https://pypi.org/project/temporalio/) ## Highlights - Memos can be added and modified inside a workflow by calling `upsert_memo` method. - Executing local activities which do not exist will fail the workflow task instead of the activity - Application failures can specify a category to control logging and metrics behavior of activity failures - Activities can be paused via `temporal activity pause`, which will interrupt the activity's execution with a cancel-like exception ### | Low | 5/30/2025 |
| 1.11.1 | [PyPI](https://pypi.org/project/temporalio/) This is a patch release fixing a bug that would cause a Worker using the older Build-ID-based versioning APIs to fail to receive tasks. ## Specific Changes 2025-05-08 - 820218c9 - Fix incorrectly set legacy build id options (#859) | Low | 5/9/2025 |
| 1.11.0 | [PyPI](https://pypi.org/project/temporalio/) ## Highlights ## Priority (Pre-release) Users can now set a priority key when scheduling a workflow, activity or child workflows. The priority key will be used to help prioritize certain tasks over others when there is a backlog. Priority is currently not supported in any OSS Temporal release, but support will be coming soon. To experiment with this feature please see the [pre-release development server](https://github.com/temporalio/cli/rele | Low | 4/23/2025 |
| 1.10.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Python 3.13 is officially supported Python 3.13 is now officially supported and Python 3.8 is no longer supported. ### Pydantic is officially supported The SDK now contains a data converter that supports conversion of all types supported by Pydantic to and from JSON. In addition to Pydantic models, these include all `json.dump`-able types, various non-`json.dump`-able standard library types such as dataclasses, ty | Low | 2/18/2025 |
| 1.9.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Update-With-Start (experimental) Update-with-start sends an update request and starts a workflow if necessary. A `WorkflowIDConflictPolicy` must be specified. If the workflow execution is not running, then a new workflow execution is started and the update is sent in the first workflow task. Alternatively, if the specified workflow execution is running then, if the `WorkflowIDConflictPolicy` is `USE_EXISTING`, the u | Low | 12/23/2024 |
| 1.8.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights * New `@workflow.init` decorator allows `__init__` to receive the workflow arguments. This can be useful for message handlers, since these may execute before the `@workflow.run` method. ## Specific Changes 2024-09-24 - 0995ae0 - Workflow init (#645) 2024-09-25 - 3cf1b85 - Change client-side default to match server-side default (#649) 2024-09-25 - a1b5d65 - cargo update -p quinn-proto (#651) 2024-09-30 - 2e6d742 - | Low | 10/10/2024 |
| 1.7.1 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights This is mostly a bugfix release meant to address: * Unable to send OpenTelemetry metrics over TLS * Sporadic activity completion RPC cancellation ## Specific Changes 2024-08-26 - 4e97841 - Create and upload junit-xml artifacts (#617) 2024-08-26 - 927abdc - Start requiring pyright typechecking (#619) 2024-08-27 - 4aef4bf - Stack trace on deadlock detection exception (#626) 2024-08-27 - 7af99d0 - Fix exception-s | Low | 9/11/2024 |
| 1.7.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Workflow Update changes #### 💥 Breaking change on `start_update` `wait_for_stage=WorkflowUpdateStage.ACCEPTED` is now required when starting an update with `temporalio.client.WorkflowHandle.start_update`. Although no other `wait_for_stage` value is currently valid, making it required emphasizes that an update caller must wait for a response from the worker, whether using `start_update` or `execute_update` (in cont | Low | 8/20/2024 |
| 1.6.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Safe Eviction The internal eviction logic has been overhauled to make sure that asyncio tasks are completed before a workflow is removed from the cache and garbage collected. For all properly running workflows this should not cause any issues. However, workflows that may have been developed in invalid ways in the past could have a problem being evicted from cache and will log as such. Users should keep an eye out fo | Low | 5/7/2024 |
| 1.5.1 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights This is mostly a bug-fix and small-issue release. There are no large notable highlights. ## Specific Changes 2024-01-10 - e3630ef - Fix line number in workflow.logger (#460) 2024-01-11 - 0bff022 - Add `wheel` to dev-dependencies (#457) 2024-01-12 - 10d099b - Fix typing of methods for pyright (#461) 2024-01-12 - 4904054 - Add build id to workflow info (#458) 2024-01-29 - 02a974c - Modularize gen-protos script (#46 | Low | 2/27/2024 |
| 1.5.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Drop Python 3.7 support Python 3.7 is EOL and is not supported by this library. In addition, we also added CI to confirm 3.12 works properly. ### Fix upserting new search attributes Last release, a bug was introduced that caused an error when upserting search attributes that weren't set on start. This has been fixed. ## Specific Changes 2023-11-16 - 06cfd03 - Drop Python 3.7 support, ensure 3.12 support, | Low | 1/9/2024 |
| 1.4.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Typed Search Attributes Previously, search attributes were untyped dictionaries with string keys and list values. This causes ambiguity on what types a search attribute key represents and leads to errors. Also, the way search attributes were created or upserted allowed mistakes to occur and was not clear to the server exactly what was expected. Among other classes, `temporalio.common.TypedSearchAttributes` and `t | Low | 11/8/2023 |
| 1.3.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Dynamic Workflows, Activities, Signals, and Queries `dynamic=True` can be added to `@workflow.defn`, `@activity.defn`, `@workflow.signal`, and `@workflow.query` to make them "dynamic". This means they are unnamed and are called if no other workflow/activity/signal/query match a name from the server when called. The workflow run or activity signature must be a single parameter typed with `Sequence[temporalio.common.R | Low | 7/24/2023 |
| 1.2.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights No significant changes from previous version, mostly bug fixes. ## Specific Changes 2023-03-30 - 4ad2e64 - Use CDN for README image, fixes #302 (#308) 2023-03-30 - 61166af - Minor doc update (#305) 2023-03-30 - 72bdca7 - Update core (#307) 2023-03-30 - d790468 - Call JSON type converters recursively (#304) 2023-04-03 - dbf96fd - Pass through global telemetry tags (#303) 2023-05-01 - a4224a2 - Update core and rel | Low | 5/1/2023 |
| 1.1.0 | Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Scheduling API Python client now has support for creating and working with schedules. ## 💥 Breaking Changes When a workflow is already running, we will now raise a `WorkflowAlreadyStartedError` error when trying to start instead of the default `RPCError` we do for all other errors. ## Specific Changes 2023-01-13 - 1a260c3 - Mark local activities as experimental (#252) 2023-01-13 - fdf8b65 - Fail activi | Low | 2/23/2023 |
| 1.0.0 | # First Stable Release! 🎉 **This is the first stable release of the Python SDK!** Since Python is now GA, we provide the same stability guarantees as all other SDKs - primarily that we vow not to break workflow history in newer versions. Get from [PyPI](https://pypi.org/project/temporalio/). ## 💥 Breaking Changes Minor change since last beta - for those configuring a custom runtime for telemetry purposes via the experimental `temporal.bridge.runtime.Runtime`, they must now use the | Low | 1/5/2023 |
| 0.1b4 | **⚠️ THIS IS A BETA RELEASE AND COMPATIBILITY MAY NOT BE MAINTAINED** Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Support for both Protobuf 3.x and 4.x libraries We now generate Protobuf via 3.x and ensure it works with 3.x and 4.x Python libraries. ### Sync activities now raise exception in thread on cancellation Now, unless opted out, sync multithread activities will raise an exception in thread when cancellation is received. ### Simplify design | Low | 12/7/2022 |
| 0.1b3 | **⚠️ THIS IS A BETA RELEASE AND COMPATIBILITY MAY NOT BE MAINTAINED** Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Workflow Sandbox There is now an enabled-by-default workflow sandbox that attempts to ensure determinism via workflow isolation and restricted access to known non-deterministic standard library calls. If you are importing third-party libraries inside the same file as your workflow, this can incur a noticeable perf/mem penalty. Also, if you | Low | 11/14/2022 |
| 0.1b2 | **⚠️ THIS IS A BETA RELEASE AND COMPATIBILITY MAY NOT BE MAINTAINED** Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Test Framework `temporalio.testing` package now includes an `ActivityEnvironment` for mocking heartbeating and cancellation for activity code. See https://github.com/temporalio/sdk-python#testing-1 for more details. `temporalio.testing` package also now includes a `WorkflowEnvironment` for testing workflows. The `WorkFlowEnvironment` can be | Low | 9/20/2022 |
| 0.1b1 | **⚠️ THIS IS A BETA RELEASE AND COMPATIBILITY MAY NOT BE MAINTAINED** Get from [PyPI](https://pypi.org/project/temporalio/) ## Highlights ### Updates * Instead of `http://host:port`, the target endpoint is now `host:port` to align with other SDKs (warns if scheme is present, will be an error next version). * Support for activities as methods on instances instead of just top-level functions. Using an instance with, say a DB client as an instance property, is a good way to have it acc | Low | 8/5/2022 |
| 0.1a2 | **⚠️ THIS IS AN ALPHA RELEASE AND COMPATIBILITY WILL _NOT_ BE MAINTAINED** ## Highlights ### Workflows This release includes full Temporal workflow support. ### Activity Definitions Activities are now marked with `@activity.defn` and name can be overridden there instead of needing to provide a dict to the worker. ### macOS M1 Support macOS ARM-based packages are now uploaded to PyPI. ## Specific Changes 2022-03-18 - c1efe42 - Readme updates (#13) 2022-03-22 - fc528ee | Low | 6/13/2022 |
| 0.1a1 | **⚠️ THIS IS AN ALPHA RELEASE AND COMPATIBILITY WILL _NOT_ BE MAINTAINED** ## Highlights ### Initial release! This release includes: * Temporal client capable of doing most Temporal things * Activity-only workers for running Python activities from workflows in another SDK language * Support for Windows x64, macOS x64, and Linux x64 (glibc >= 2.31) This release does not include: * Workflow worker support * Async activity support (in client or worker) * Support for Windows ar | Low | 3/18/2022 |