Install & Compatibility
Where this runs
tested against v3.2.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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.285s · 20.3MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.7s · import 0.244s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StateChart
✓ from statemachine import StateChart, State
Introduced in v3.0, recommended for new projects and statechart features.
StateMachine
✓ from statemachine import StateMachine, State
Main class in v2.x, preserved in v3.x for backward compatibility. Use StateChart for new features.
This quickstart defines a `TrafficLightMachine` as a `StateChart` with three states: `green`, `yellow`, and `red`. A `cycle` event transitions the light sequentially. It includes `before_cycle`, `on_enter_red`, and `on_exit_red` methods, which are automatically called during transitions and state entries/exits respectively.
from statemachine import StateChart, State
class TrafficLightMachine(StateChart):
"A traffic light machine"
green = State(initial=True)
yellow = State()
red = State()
cycle = (
green.to(yellow)
| yellow.to(red)
| red.to(green)
)
def before_cycle(self, event: str, source: State, target: State):
return f"Running {event} from {source.id} to {target.id}"
def on_enter_red(self):
print("Don't move.")
def on_exit_red(self):
print("Go ahead!")
sm = TrafficLightMachine()
print(f"Initial state: {sm.current_state.id}")
print(sm.send("cycle"))
print(f"Current state: {sm.current_state.id}")
print(sm.send("cycle"))
print(f"Current state: {sm.current_state.id}")
print(sm.send("cycle"))
print(f"Current state: {sm.current_state.id}")
Debug
Known issues
breakingVersion 3.0.0 introduces `StateChart` as the new recommended base class for full statechart support (e.g., compound states, parallel regions, history states) and modern defaults. While the older `StateMachine` class is preserved, it maintains 2.x defaults and may not expose all new features. New projects should prefer `StateChart`.fixFor new projects or to use full statechart capabilities, import and inherit from `StateChart` instead of `StateMachine`. Refer to the upgrade guide for migration details from 2.x.
affects: >=3.0.0
breakingIn version 2.0.0, the `StateMachine.run()` method was removed in favor of `StateMachine.send()` for triggering events. Additionally, the default event processing model changed to 'Run-to-completion (RTC)', which affects how nested events are handled.fixReplace calls to `sm.run('event')` with `sm.send('event')`. Review documentation on the RTC processing model if your state machine relies on specific nested event behaviors. affects: >=2.0.0
breakingVersion 2.0.0 removed `State.identification`, replacing it with `State.id`. State names also became optional, automatically deriving from the class variable name by default.fixUpdate any code referencing `State.identification` to `State.id`. Consider relying on automatic state naming unless an explicit custom name is required.
affects: >=2.0.0
gotchaDiagram generation (using `python-statemachine[diagrams]`) requires the external `Graphviz` command-line tool (`dot`) to be installed on your system, in addition to the Python `pydot` dependency.fixEnsure `Graphviz` is installed and accessible in your system's PATH (e.g., `sudo apt install graphviz` on Debian/Ubuntu, or follow instructions for other OS).
affects: All versions with diagram support
deprecatedFrom version 2.2.0, the library warns if non-final states do not have outgoing transitions, indicating potential 'trapped' states. This check is currently a warning but will become an exception by default (`strict_states=True`) in the next major release.fixEnsure all non-final states have at least one outgoing transition. If intentional, you can silence the warning or explicitly set `strict_states=False` on your `StateMachine`/`StateChart` class. Prepare for `strict_states=True` to become the default in future major releases.
affects: >=2.2.0
Upgrade
Version history
3.2.1latest on PyPI · released Aug 1, 2026
Audit
Dependencies
pydotoptionalRequired for generating state machine diagrams.