Run your XState or Stately JSON unmodified, or define machines in plain Python. Async and sync engines share one algorithm. A CLI that proves its generated code rebuilds your machine before it writes a file. Zero dependencies.
$ pip install xstate-statemachine
pending
event —
Export from Stately and run it. Nested, parallel, history, guards, delays, invoke, actors, tags, meta.
from xstate_statemachine import create_machine, Interpreter
machine = create_machine(json.load(open("order.json")))
interp = await Interpreter(machine).start()Interpreter for asyncio, SyncInterpreter for everything else. Same core; cannot drift.
actionErrorPolicy: "rollback" restores state and context. strict mode raises at the call site. Every policy, with a runnable example →
Inject a Clock. SimulatedClock fires a 30‑second timeout in microseconds.
await send("SUBMIT", wait=True) hands you a Receipt the moment the step has run. send_priority jumps the queue; the inbox is bounded with backpressure.
Versioned snapshots that refuse a structurally different machine. Pending events survive restarts.
context_type=MyCtx flows a TypedDict to interp.context. A typo'd key is a checker error.
Every Python block in this site is executed in CI. Every link is resolved. 34 runnable examples.
Pick the style that matches your team. All compile to the same runtime.
from xstate_statemachine import (
State, StateMachine, SyncInterpreter, action, guard
)
class TrafficLight(StateMachine):
machine_id = "trafficLight"
# States
green = State("green", initial=True)
yellow = State("yellow")
red = State("red")
# Transitions
slow_down = green.to(yellow, event="TIMER")
stop = yellow.to(red, event="TIMER")
go = red.to(green, event="TIMER")
@action
def log_change(self, interpreter, context, event, action_def):
print(f"Light: {interpreter.active_state_ids}")
# Run it
machine = TrafficLight.create_machine()
interp = SyncInterpreter(machine).start()
interp.send("TIMER") # green → yellow
interp.send("TIMER") # yellow → red
interp.stop()from xstate_statemachine import MachineBuilder, SyncInterpreter
machine = (
MachineBuilder("trafficLight")
.state("green", initial=True)
.state("yellow")
.state("red")
.transition("green", "TIMER", "yellow")
.transition("yellow", "TIMER", "red")
.transition("red", "TIMER", "green")
.build()
)
interp = SyncInterpreter(machine).start()
interp.send("TIMER") # green → yellow
interp.send("TIMER") # yellow → red
interp.stop()from xstate_statemachine import State, build_machine, SyncInterpreter
green = State("green", initial=True,
on={"TIMER": "yellow"})
yellow = State("yellow", on={"TIMER": "red"})
red = State("red", on={"TIMER": "green"})
machine = build_machine(
id="trafficLight",
states=[green, yellow, red],
)
interp = SyncInterpreter(machine).start()
interp.send("TIMER") # green → yellow
interp.send("TIMER") # yellow → red
interp.stop()from xstate_statemachine import create_machine, SyncInterpreter
config = {
"id": "trafficLight",
"initial": "green",
"states": {
"green": {"on": {"TIMER": "yellow"}},
"yellow": {"on": {"TIMER": "red"}},
"red": {"on": {"TIMER": "green"}},
}
}
machine = create_machine(config)
interp = SyncInterpreter(machine).start()
interp.send("TIMER") # green → yellow
interp.send("TIMER") # yellow → red
interp.stop()Against the three other Python state-machine libraries in common use — transitions 0.9.3, python-statemachine 3.2.1, sismic 1.6.11, checked against the installed packages on 2026-09-19. A dash means the capability exists in a limited form (a thread-based timeout extension, an optional-dependency diagram, listener callbacks rather than a plugin API).
| Feature | XState-StateMachine | transitions | python-statemachine | sismic |
|---|---|---|---|---|
| Hierarchical states | ||||
| Parallel regions | ||||
Delayed transitions (after) | ||||
| Invoked services / child machines | ||||
| Actor model (spawn, sendTo, escalate) | ||||
| XState v5 JSON compatibility | ||||
| Declarative definition (JSON / YAML / SCXML) | ||||
| Async and sync engines | ||||
| Virtual-time clock for tests | ||||
| Deep snapshot / restore | ||||
| Bounded inbox with overflow policy | ||||
| Build-time validation | ||||
| Plugin / inspection hooks | ||||
| CLI code generator | ||||
| Diagram export | ||||
| Zero runtime dependencies |
Same machine shape, each library through its own idiomatic API. Higher is better; bold is fastest in the row.
| Scenario | XState-StateMachine | transitions | python-statemachine | sismic |
|---|---|---|---|---|
| Flat toggle events/s | 82,562 | 173,287 | 11,850 | 16,155 |
| Guard + action events/s | 75,926 | 146,365 | 10,170 | 14,978 |
| 3-level nested events/s | 34,023 | 10,485 | 3,302 | 6,248 |
| Parallel regions events/s | 56,239 | 7,468 | 4,751 | 5,930 |
| Delayed transitions timers/s | 11,609 | 72 | 4,664 | 6,805 |
| 1,000 instances instances/s | 51,923 | 47,326 | 4,852 | 9,307 |
| Construction machines/s | 12,442 | 10,475 | 1,813 | 362 |
| Native asyncio events/s | 32,107 | 47,620 | 8,339 | — |
transitions is faster on flat machines because it is a transition table, not a statechart
engine — no configuration set, no entry/exit ordering, no internal queue. The moment states nest or run in
parallel, that algorithm is what the others have to emulate, and XState-StateMachine is 3.2–7.5× faster
than every library that does implement statecharts. Since 0.8.1 it is also the fastest of the four to construct
(1.19× transitions) and to fan out to 1,000 instances (1.10×) — a single-pass parser and
slotted interpreters — while still running the full build-time validator on every create_machine().
Measured 2026-09-19 on 0.8.1, all libraries in one session:
Python 3.14, median of 7 runs, GC disabled, setup excluded. Reproduce with benchmarks/competitors/run.py;
full table and caveats in the
benchmark README,
our own scaling curves in Production Characteristics.
Start with the guide, or read the whole API on one page.