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.

Development

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

Integration tests use Docker:

docker compose -f docker-compose.test.yml up -d --build --wait
pytest tests/integration/ -v
docker compose -f docker-compose.test.yml down -v

License

MIT

Release files for durable-workflow 2.0.1

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.0.1
File	Size	Uploaded
durable_workflow-2.0.1.tar.gz	343.1 kB	Sep 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for durable-workflow 2.0.1
File	Interpreter	ABI	Platform	Reset
durable_workflow-2.0.1-py3-none-any.whl 196.2 kB Sep 2, 2026	Python 3	none	any	Details

Total release size: 539.4 kB

Release files / durable_workflow-2.0.1.tar.gz

Download URL	durable_workflow-2.0.1.tar.gz
Size	343.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`9dcef113c0b5dfed9c21f9d70a7c49d1c262268f07ed38f9cbb5c31a0f27be2d`
BLAKE2b-256 checksum How to use checksums	`e893decddacc5bc41f0dc5a3a642437f59a3b559fc5d4b60d75b124e17a57121`
Upload date	Sep 2, 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.0.1-py3-none-any.whl

Download URL	durable_workflow-2.0.1-py3-none-any.whl
Size	196.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4a099f496bd8fd04b69376d00e586bf0f4a2bc01177e5351f9a7539958175472`
BLAKE2b-256 checksum How to use checksums	`27351f21b55adc585b343f3b3e9158ac8ac53298967002a9f62b2e4d1b625b7b`
Upload date	Sep 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.14`