Registry / workflow / hatchet-sdk

hatchet-sdk

library1.38.1pypypi✓ verified 24d ago

This is the official Python SDK for Hatchet, a distributed, fault-tolerant task queue. The SDK allows you to easily integrate Hatchet's task scheduling and workflow orchestration capabilities into your Python applications, supporting the development of mission-critical AI agents, durable workflows, and background tasks. It is actively maintained, with regular updates and a focus on durability and scalability.

workflow llm-agents ai-ml database

pip install hatchet-sdk

package ↗homepage ↗

INSTALL

IMPORT

SIG · HATCHET-SDK

H

hatchet-sdk

workflowpythonv1.38.1

Install

9.8s avg

Import

7205ms

Disk

79MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.38.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 6.142s · 81MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 9.8s · import 5.386s · 78MB

79MB installed

● package 79MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Hatchet

✓ from hatchet_sdk import Hatchet

Context

✓ from hatchet_sdk import Context

DurableContext

✓ from hatchet_sdk import DurableContext

EmptyModel

✓ from hatchet_sdk import EmptyModel

This quickstart initializes the Hatchet client using environment variables for the API token and host, defines a simple task with the `@hatchet.task()` decorator, registers it with a worker, and starts the worker to process incoming tasks. Replace 'YOUR_HATCHET_CLIENT_TOKEN' with your actual token.

import os from hatchet_sdk import Hatchet, Context, EmptyModel # Initialize the Hatchet client. HATCHET_CLIENT_TOKEN is required. # HATCHET_CLIENT_HOST_PORT defaults to 'localhost:7077' if not set. hatchet = Hatchet( token=os.environ.get('HATCHET_CLIENT_TOKEN', 'YOUR_HATCHET_CLIENT_TOKEN'), host_port=os.environ.get('HATCHET_CLIENT_HOST_PORT', 'localhost:7077') ) # Define a simple Hatchet task using the decorator @hatchet.task() def hello_world(input: EmptyModel, context: Context) -> dict[str, str]: print(f"Executing task hello_world with input: {input.model_dump_json()}") return {"message": "Hello, world from Hatchet!"} # Create a worker and register the task worker = hatchet.worker("my-python-worker") worker.register_task(hello_world) print("Starting Hatchet worker... Press Ctrl+C to stop.") # Start the worker to listen for and execute tasks worker.start() print("Hatchet worker stopped.")

Debug

Known issues

breakingMigration from V0 to V1 SDK: `timeout` and `schedule_timeout` fields are now `datetime.timedelta` objects instead of strings (e.g., `"10s"` becomes `timedelta(seconds=10)`).

fix

Update string-based timeouts to `datetime.timedelta` objects.

affects: All V1.x.x versions when migrating from V0 SDK.

breakingMigration from V0 to V1 SDK: External-facing protobuf objects (e.g., `StickyStrategy`, `ConcurrencyLimitStrategy`) have been replaced by native Python enums.

fix

Replace direct usage of protobuf objects with their corresponding Python enum equivalents.

affects: All V1.x.x versions when migrating from V0 SDK.

breakingMigration from V0 to V1 SDK: Asynchronous methods throughout the SDK are now prefixed by `aio_` (e.g., `workflow.run()` is now `workflow.aio_run()` for async execution).

fix

Prefix asynchronous method calls with `aio_`.

affects: All V1.x.x versions when migrating from V0 SDK.

breakingMigration from V0 to V1 SDK: The `max_runs` parameter on the worker has been renamed to `slots`.

fix

Update `max_runs` parameter to `slots` when configuring workers.

affects: All V1.x.x versions when migrating from V0 SDK.

breakingMigration from V0 to V1 SDK: Tasks now have a new signature, taking `input` and `context` as arguments, and are typically declared using `@hatchet.task()` instead of requiring an explicit workflow definition first.

fix

Update task function signatures to accept `input` and `context` arguments and use the `@hatchet.task()` decorator.

affects: All V1.x.x versions when migrating from V0 SDK.

gotchaV0 Hatchet engine is not compatible with V1 workflows. The V0 engine entered End-of-Life on September 30, 2025. Ensure your Hatchet engine is upgraded to V1 or later when using the V1 Python SDK.

fix

Upgrade your Hatchet engine to V1 or later to ensure compatibility with the V1 Python SDK.

affects: V1.x.x SDK with V0 engine.

gotchaConcurrency keys that reference fields in a task's `input` will be checked for validity at runtime. The `input_validator` Pydantic model for the task must explicitly contain any fields used in a concurrency key (e.g., if key is `input.user_id`, `input_validator` must have a `user_id` field).

fix

Ensure your task's `input_validator` Pydantic model explicitly defines all fields used in concurrency keys.

affects: All V1.x.x versions.

Errors

Common errors & fixes

Warning: THE TIME TO START THE STEP RUN IS TOO LONG, THE MAIN THREAD MAY BE BLOCKED.

This warning indicates that a Hatchet task is performing synchronous (blocking) I/O or CPU-bound work directly within an asynchronous context, which blocks the asyncio event loop and negatively impacts worker performance.

fix

Rewrite blocking operations (e.g., API calls with `requests`, synchronous database drivers) to their asynchronous equivalents (e.g., `aiohttp`, `asyncpg`), or offload CPU-bound tasks to a separate thread or process using `asyncio.to_thread()` or `ProcessPoolExecutor`.

ValueError: HATCHET_CLIENT_TOKEN environment variable not set or invalid JWT

The Hatchet client requires an API token for authentication, which must be provided via the `HATCHET_CLIENT_TOKEN` environment variable or explicitly passed during client initialization. This error occurs if the token is missing or malformed (not a valid JWT).

fix

Obtain a valid API token from the Hatchet dashboard or your self-hosted instance and set it as an environment variable: `export HATCHET_CLIENT_TOKEN="<your-api-token>"`. Alternatively, pass the token directly when initializing the `Hatchet` client: `hatchet = Hatchet(token="<your-api-token>")`.

ModuleNotFoundError: No module named 'hatchet_sdk'

This error occurs when the `hatchet-sdk` library is not installed in the Python environment, or the environment where the code is being run does not have access to the installed package.

fix

Install the Hatchet SDK using pip: `pip install hatchet-sdk`. If using Poetry, use `poetry add hatchet-sdk`. Ensure you are running your script in the correct Python environment where the package was installed.

grpc._channel._MultiThreadedRendezvous: <_MultiThreadedRendezvous of RPC that terminated with: status = StatusCode.UNAVAILABLE details = "failed to connect to all addresses" debug_error_string = "" >

This gRPC error typically means the Hatchet engine (server) is unreachable or actively refusing connections. Common reasons include the engine not running, incorrect `HATCHET_CLIENT_HOST_PORT`, firewall issues, or TLS/SSL configuration mismatches between the client and server.

fix

Verify the Hatchet engine is running and accessible. Check the `HATCHET_CLIENT_HOST_PORT` environment variable to ensure it points to the correct host and port (e.g., `localhost:7070`). If self-hosting, ensure TLS settings (`HATCHET_CLIENT_TLS_STRATEGY`) match the server's configuration; for local development, you might set `HATCHET_CLIENT_TLS_STRATEGY=none`. Check network connectivity and firewall rules.

Upgrade

Version history

1.38.1latest on PyPI · released Aug 25, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

31 hits · last 30 days

node

26

OpenAI (training)

1

Resources

packagehttps://pypi.org/project/hatchet-sdk/ ↗

homepagehttps://hatchet.run ↗

hatchet-sdk — pip install hatchet-sdk · libregistry