Python SDK · release candidate

Durable workflows, written in Python.

Build async clients and workers for long-running, retryable work. Start with a local self-hosted Server—no Cloud account is required.

Run your first workflow → Read the SDK guide Browse API reference

Python 3.10+Async-firstFully typed

Install

pip install 'durable-workflow~=2.0.0rc0'

The compatible-release constraint follows the supported 2.0 prerelease channel without pinning this page to one release-candidate number.

View on PyPISource on GitHub

How the pieces fit

A client asks the runtime to do durable work. A worker receives tasks and dispatches them to your workflow and activity code.

01ClientStarts and controls workflow runs from your app.Client API → 02WorkerPolls a task queue and dispatches registered handlers.Worker API → 03WorkflowDescribes replay-safe orchestration and durable decisions.Workflow API → 04ActivityPerforms side effects such as API calls and database work.Activity API →

Run your first local workflow

This source-free development path runs the compatibility-qualified Server image on your machine, then connects one Python client and worker to it.

1. Start the compatible Server

Docker keeps this first run local. The image tag below is rendered from the SDK's compatibility authority, alongside the package version shown on this page.

export DW_SERVER_IMAGE='durableworkflow/server:2.0.0-rc.32'
export DW_AUTH_TOKEN=dev-token
docker volume create durable-workflow-python
docker run --rm -v durable-workflow-python:/app/database \
  -e DW_AUTH_DRIVER=token -e DW_AUTH_TOKEN="$DW_AUTH_TOKEN" \
  "$DW_SERVER_IMAGE" server-bootstrap
docker rm -f durable-workflow-python-server >/dev/null 2>&1 || true
docker run -d --name durable-workflow-python-server -p 8080:8080 \
  -v durable-workflow-python:/app/database \
  -e DW_AUTH_DRIVER=token -e DW_AUTH_TOKEN="$DW_AUTH_TOKEN" \
  "$DW_SERVER_IMAGE"
until curl -sf http://localhost:8080/api/ready >/dev/null; do sleep 1; done

2. Save greeter.py

import asyncio
from uuid import uuid4

from durable_workflow import Client, Worker, activity, workflow


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


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


async def main() -> None:
    async with Client(
        "http://localhost:8080",
        token="dev-token",
        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=f"greeting-{uuid4().hex}",
            task_queue="python-workers",
            input=["world"],
        )
        await worker.run_until(workflow_id=handle.workflow_id, timeout=30.0)
        print(await handle.result(timeout=10.0))


asyncio.run(main())

3. Run it

python greeter.py

The client starts a durable workflow instance. The worker executes the workflow and its activity, and the final line prints Hello, world!. Continue with the complete Python SDK guide for messages, retries, tests, credentials, and production worker operation.

Choose who runs the runtime

Your Python workflow code and task queue model stay the same. The endpoint, credentials, and operating boundary change.

Available without an account

Self-hosted Server

Run the published Server image with your database, authentication policy, and operational controls.

Open the Server guide →

Managed runtime · limited access

Durable Workflow Cloud

Use a provisioned namespace URL and separate client and worker credentials while Durable Workflow operates the runtime.

Request early access →

Go deeper when you need it

Python SDK guideTutorials, architecture, testing, and operations.Read the guide → Generated API referenceSignatures, return types, exceptions, and public modules.Browse reference → PyPI packageRelease files, Python requirements, and package metadata.Open PyPI → GitHub repositorySource, examples, changelog, and contribution guide.View source →

Versioning

This site is generated from the SDK source and keeps exact release identities in one machine-owned compatibility authority. It currently qualifies SDK 2.0.0-rc.31 with durableworkflow/server:2.0.0-rc.32. The SDK and Server advance independently; use the versions shown here together.