---
id: python-statemachine
version: "3.2.1"
license: MIT License
license_treatment: permissive
maintenance: active
---

# python-statemachine — Python Finite State Machines made easy.

License: permissive · Maintenance: active · Downloads: 1.3M/mo

## What it is and what it does

Python StateMachine is a declarative state machine and statechart library that lets you model complex workflows and control logic as classes with states and transitions. You define states as class attributes, connect them with transition rules, and attach callbacks (guards, entry/exit handlers) that run when events fire or states change. The library handles both synchronous and asynchronous callbacks transparently, automatically detecting async functions and switching to an async engine when needed.

The package supports flat finite state machines for simple workflows, but also hierarchical compound states for breaking complex behavior into nested levels, parallel regions for concurrent sub-machines, history states for remembering previous positions, and conditional transitions guarded by custom predicates. It includes error handling (runtime exceptions become error.execution events), eventless transitions that fire automatically when conditions are met, and introspection methods like checking active states or generating text/graphical representations of the machine. With no external runtime dependencies and support for Python 3.10+, it integrates cleanly into sync and async codebases.

Use it for:

- Model approval workflows with conditional routing: pending → approved or rejected based on score guards.
- Implement document editing pipelines with nested states: editing (draft/review) → published, tracking hierarchical progress.
- Build deployment orchestration with parallel regions: compile and test simultaneously, fire done event only when all regions finish.
- Create traffic light or traffic-control systems with cyclic state transitions and entry/exit side effects.
- Handle async task workflows where callbacks are coroutines and state transitions await completion.
- Implement error recovery: catch runtime exceptions as error.execution events and transition to failure states.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Defines finite state machines and statecharts with a declarative Python API, supporting flat states, compound hierarchies, parallel regions, history states, guards, and both sync and async callbacks.

Yes. The library is production-stable (Development Status 5), actively maintained, has no known vulnerabilities, zero runtime dependencies, and a clean declarative API. Install it if you need to model workflows, control logic, or any system with discrete states and event-driven transitions — from simple state machines to complex statecharts with hierarchy and concurrency. The async support and low friction make it suitable for modern Python projects.

## Install

pip install python-statemachine
uv add python-statemachine
poetry add python-statemachine

## Installing python-statemachine

Before you install: Low friction: pure Python wheel with no runtime dependencies. Active maintenance with a recent release (13 days old) and 1278 repository stars.

License in practice: MIT License (permissive) — you can use, modify, and distribute this package freely in commercial and open-source projects with minimal restrictions.

Quickstart:

from statemachine import StateChart, State

class TrafficLight(StateChart):
    green = State(initial=True)
    yellow = State()
    red = State()
    cycle = green.to(yellow) | yellow.to(red) | red.to(green)

sm = TrafficLight()
sm.send("cycle")
print(sm.green.is_active)

Requires Python 3.10 or later.

Verify before relying:

- Whether the library supports pickling or serialization of state machine instances.
- Performance characteristics under high-frequency event dispatch or deeply nested compound states.
- Availability and scope of visualization/diagram generation beyond the basic graph example shown.

## Package facts

- License: MIT License (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.3M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

state machine library python, finite state machine fsm, statecharts declarative, async state transitions, workflow state management, hierarchical state machine, parallel state regions, state-machine, workflow-engine, async-ready

[View on SkillFed](https://skillfed.io/packages/python-statemachine) · [View on PyPI](https://pypi.org/project/python-statemachine/)