Skip to main content

​
Requirements

  • Python 3.10 or higher
  • pip, poetry, or uv

​
Installation

pip install hatchet-sdk

​
OpenTelemetry extra

Install the optional otel extra to enable distributed tracing with OpenTelemetry: 
pip install "hatchet-sdk[otel]"
This installs opentelemetry-api, opentelemetry-sdk, opentelemetry-instrumentation, opentelemetry-distro, opentelemetry-exporter-otlp, and opentelemetry-exporter-otlp-proto-http.

​
Setup

1

Get an API token

Obtain your API token from the Hatchet Cloud dashboard or your self-hosted Hatchet instance.The token is a JWT that embeds your tenant ID and server addresses, so the SDK can read them automatically.
2

Set environment variables

Export your token so the SDK can pick it up automatically:
export HATCHET_CLIENT_TOKEN="<your-api-token>"
For self-hosted deployments, also set the host and port:
export HATCHET_CLIENT_TOKEN="<your-api-token>"
export HATCHET_CLIENT_HOST_PORT="localhost:7070"
The SDK also reads from .env, .env.hatchet, .env.dev, and .env.local files automatically.
3

Initialize the client

Import Hatchet and create an instance. With the environment variable set, no additional configuration is needed:
from hatchet_sdk import Hatchet

hatchet = Hatchet()
Enable debug logging by passing debug=True:
hatchet = Hatchet(debug=True)
4

Define and run your first task

from hatchet_sdk import Context, EmptyModel, Hatchet

hatchet = Hatchet()

@hatchet.task()
def hello(input: EmptyModel, ctx: Context) -> dict[str, str]:
    return {"message": "Hello, world!"}

# Trigger the task and wait for the result
result = hello.run()
print(result)  # {"message": "Hello, world!"}

​
Environment variable reference

VariableDescriptionDefault
HATCHET_CLIENT_TOKENAPI token (required)—
HATCHET_CLIENT_HOST_PORTgRPC server host and portRead from token
HATCHET_CLIENT_NAMESPACENamespace prefix for workflow and event names""
HATCHET_CLIENT_TLS_STRATEGYTLS strategy (tls or none)"tls"
The SDK validates that HATCHET_CLIENT_TOKEN starts with ey (a valid JWT prefix). Tokens from the dashboard start with ey — if you see an error about token format, ensure you are not using a non-JWT token.

Build docs developers (and LLMs) love

Get started for freeTalk to us