python-statemachine
Python Finite State Machines made easy.
Decision gist · record as of 2026-08-14
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.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.10 or later.
- Low friction: pure Python wheel with no runtime dependencies.
- Active maintenance with a recent release (13 days old) and 1278 repository stars.
License · maintenance · safety
MIT License (permissive) — MIT License (permissive) — you can use, modify, and distribute this package freely in commercial and open-source projects with minimal restrictions.
last release 2026-08-01 (13 days) · last repo commit 2026-08-01 · 1,278 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 1,316,242 downloads/mo, #4,068 on PyPI
Alternatives
Verify before relying
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)- 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.
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 on this page. Verify before relying on it.
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
python-statemachine on PyPI
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.
Requires Python 3.10 or later.
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)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 the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | None |
| Maintenance | Actively maintained 13 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 1,316,242 / month, #4,068 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableFramework :: AsyncIOFramework :: DjangoIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseNatural Language :: EnglishProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Topic :: Home AutomationTopic :: Software Development :: Libraries |
Evidence: python_statemachine-3.2.1-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “statecharts declarative”
- python-statemachineDefines finite state machines and statecharts with a declarative…
- agent-framework-declarativeEnables building agents from YAML specifications using Microsoft's…
- magic-filterProvides a filter mechanism based on dynamic attribute access that…
Give your agent the search over MCP, or paste the wish link into any chat.
More Libraries packages
urllib3 is an HTTP client library that provides thread-safe connection pooling, SSL/TLS verification, multipart file uploads, request retries, compression support, and proxy handling for Python applications.
Requests is a Python HTTP library that simplifies sending HTTP/1.1 requests with automatic handling of headers, authentication, cookies, and response parsing.
Pluggy provides a plugin system that lets you define hook specifications and register implementations to be called in sequence, enabling extensible Python applications without tight coupling.
Install it if you're building an extensible application or framework.
Provides parsing, arithmetic, and recurrence rule computation for dates and times, with timezone support and iCalendar RFC compliance.
Install it if you need to parse flexible date strings, compute relative dates, handle timezones, or work with recurrence rules—it's the de facto choice for these tasks.
Six provides utility functions to write Python code that runs on both Python 2.7 and Python 3.3+, smoothing over language differences between the two versions.
pytest is a testing framework that lets you write test functions using plain assert statements and automatically discovers and runs them, with detailed failure reporting.
See also fysom · automaton · django-fsm-2 · transitions · Automat · django-fsm · django-fsm-log · pydantic-graph · aws-cdk.aws-stepfunctions · guardrails-ai