Durable Workflow Python SDK

Build durable Python workflows and activities against Durable Workflow Cloud or a self-hosted Server. The SDK uses the same language-neutral runtime protocol as the first-party PHP and Rust SDKs.

Install

pip install durable-workflow

Python 3.10 or newer is required.

Quickstart

import asyncio
from uuid import uuid4

from durable_workflow import Client, Worker, workflow, activity

@activity.defn(name="greet")
def greet(name: str) -> str:
    return f"hello, {name}"

@workflow.defn(name="greeter")
class GreeterWorkflow:
    def run(self, ctx, name):
        result = yield ctx.schedule_activity("greet", [name])
        return result

async def main():
    workflow_id = f"greet-{uuid4().hex}"
    async with Client(
        "http://server:8080",
        token="dev-token-123",
        namespace="default",
    ) as client:
        worker = Worker(
            client,
            task_queue="python-workers",
            workflows=[GreeterWorkflow],
            activities=[greet],
        )
        handle = await client.start_workflow(
            workflow_type="greeter",
            workflow_id=workflow_id,
            task_queue="python-workers",
            input=["world"],
        )
        await worker.run_until(workflow_id=workflow_id, timeout=30.0)
        result = await client.get_result(handle)
        print(result)  # "hello, world"

if __name__ == "__main__":
    asyncio.run(main())

Pass the Server origin to Client without a trailing /api. For Cloud, pass the complete namespace runtime URL exactly as provisioned. Cloud client and worker processes use separate runtime credentials:

client = Client(
    runtime_url,
    control_token=client_token,
    worker_token=worker_token,
    namespace=namespace,
)

Keep the client token in application processes and the worker token in worker processes when deploying them separately.

Capabilities

Workflows, activities, child workflows, timers, and continue-as-new
Signals, queries, validated updates, schedules, and message streams
Activity retries, timeouts, cancellation, and heartbeats
Deterministic parallel work, side effects, version markers, and sagas
Replay verification and an in-process workflow test environment
Avro payloads, external payload storage, metrics, and interceptors

See the capability matrix for the complete cross-SDK contract.

Documentation

Runtime choices

Use Durable Workflow Cloud for a managed namespace, or run the published durableworkflow/server image yourself. Workflow and activity type names, task queues, and payloads are portable between both runtime choices.

Compatibility

Stable 2.x SDK releases follow semantic versioning and negotiate runtime capabilities with Server at startup. Use stable 2.x SDK and Server channels for new applications. The compatibility guide documents protocol and upgrade guarantees.

Worker protocol and cooperative cancellation

Workers use protocol 1.20 by default. For a Server that supports only 1.19, set DURABLE_WORKFLOW_WORKER_PROTOCOL_VERSION=1.19. This changes the request protocol without enabling optional worker features.

Use request_cancellation() for bounded, replayable workflow cleanup. Opt in against a Server that advertises protocol 1.20 and the required capabilities: include cooperative_cancellation in the Worker's capabilities. Durable local callback admission also needs prepared_local_activities, with prepared_local_activity_cancellation_policies for explicit local policies. Independently cancellable scopes remain disabled.

For synchronous Nexus completion waits, the cooperative worker also negotiates nexus_cooperative_cancellation when Server advertises the installed workflow_run binding. Owned target cleanup keeps the caller pending until the Server commits delivery at the original call. Async and acceptance-only calls keep their admission behavior. Existing terminal results and recorded legacy Nexus histories retain their replay semantics.

The cooperative worker supervises async and synchronous activity callbacks independently of application heartbeats. Existing terminal cancellation remains available. See the cancellation guide for immutable context, operation policies, shielded cleanup and recovery.

Both await activity.context().heartbeat() and synchronous activity.context().heartbeat_sync() stop at an explicit Server refusal. They raise ActivityLeaseAuthorityLost with its original .reason for an elapsed deadline, closed attempt or closed run. Cancellation continues to raise ActivityCancelled. The worker submits no result or failure for an attempt whose heartbeat refused continuation, even if application code catches that exception. A heartbeat check acts only when called. Code that never heartbeats can continue until it returns, subject to independent lease/cancellation supervision; a running native thread cannot be forcibly stopped or its effects undone by the SDK.

Development

The installed durable-workflow-replay-conformance command runs an offline Python replay shard. Its sdk-python artifact pin must match the installed distribution version reported by importlib.metadata.version("durable-workflow"). The report records that installed identity separately from the declared platform tuple and fails if metadata is missing or the SDK pin differs. Replay success does not prove installation or execution of the other declared artifacts; the aggregate runner supplies its own verified installation receipts.

pip install -e '.[dev]'
ruff check src/ tests/
mypy src/durable_workflow/
pytest tests/ -m "not integration"

Integration tests use Docker:

export COMPOSE_PROJECT_NAME=sdk-python-local
docker compose -f docker-compose.test.yml up -d --build --wait
SERVER_PORT=$(docker compose -f docker-compose.test.yml port server 8080 | sed 's/.*://')
DURABLE_WORKFLOW_SERVER_URL="http://127.0.0.1:$SERVER_PORT" DURABLE_WORKFLOW_AUTH_TOKEN=test-token pytest tests/integration/ -v
docker compose -f docker-compose.test.yml down -v

Candidate cooperative cancellation qualification is explicit. In a manual CI run, supply an exact public server_commit and set cooperative_qualification to true. CI verifies that checkout, builds the candidate Server, enables protocol 1.20, runs the connected cases and retains JUnit, raw observations, image authority and exact source provenance. An optional exact native_commit mounts that public Native checkout read-only into the test stack. The image's published Composer authority stays intact and the evidence identifies the source overlay. These are source qualification runs. For a local candidate, set DURABLE_WORKFLOW_COOPERATIVE_QUALIFICATION=1 for pytest. These cases fail if the runtime does not discover the required capability. Ordinary CI uses the SDK's default protocol and skips the optional connected cooperative cases.

License

MIT

Metadata

Release files for durable-workflow 2.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for durable-workflow 2.8.0
File	Size	Uploaded	Provenance
durable_workflow-2.8.0.tar.gz	572.5 kB	Oct 21, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for durable-workflow 2.8.0
File	Interpreter	ABI	Platform	Reset
durable_workflow-2.8.0-py3-none-any.whl 302.0 kB Oct 21, 2026 Without provenance	Python 3	none	any	Details

Total release size: 874.5 kB

Release files / durable_workflow-2.8.0.tar.gz

Download URL	durable_workflow-2.8.0.tar.gz
Size	572.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`11dc35f8d4eb0e39bc47b3e9aa36b64b9893ee5458067906ef63e9be927f59bb`
BLAKE2b-256 checksum How to use checksums	`18b8562b9d0886a48ea9fdee266a2e047ebc0ac3a502d6f48b672f08eb8a14be`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Release files / durable_workflow-2.8.0-py3-none-any.whl

Download URL	durable_workflow-2.8.0-py3-none-any.whl
Size	302.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`908267666c35890fce13ab9c8e62a5c93abac78bdffbb0e56423eb3b3e57a77b`
BLAKE2b-256 checksum How to use checksums	`4cb95c38424305ccd78739263b1a0e19e65eaaa76b5d3a3bb5c8543dabef90b7`
Upload date	Oct 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Security for durable-workflow 2.8.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.