Install & Compatibility
Where this runs
tested against v0.9.3 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.056s · 18.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.050s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Machine
✓ from transitions import Machine
State
✓ from transitions import State
✗ from transitions.core import State
While `State` might be in `transitions.core`, the public API exposes it directly from `transitions` for easier access.
This quickstart demonstrates creating a simple state machine with a model, defining states and transitions, and triggering state changes. Callbacks can be attached to transitions (e.g., `before`, `after`) to execute logic.
from transitions import Machine
class Matter(object):
def __init__(self):
self.state = None # Machine will manage this
def make_hissing_noises(self):
print("HISSSSSSSSSSSSSSSS")
def disappear(self):
print("where'd all the liquid go?")
states = ['solid', 'liquid', 'gas', 'plasma']
transitions = [
{ 'trigger': 'melt', 'source': 'solid', 'dest': 'liquid', 'before': 'make_hissing_noises' },
{ 'trigger': 'evaporate', 'source': 'liquid', 'dest': 'gas', 'after': 'disappear' },
{ 'trigger': 'sublimate', 'source': 'solid', 'dest': 'gas' },
{ 'trigger': 'ionize', 'source': 'gas', 'dest': 'plasma' }
]
lump = Matter()
machine = Machine(model=lump, states=states, transitions=transitions, initial='solid')
print(f"Initial state: {lump.state}")
lump.melt()
print(f"Current state: {lump.state}")
lump.evaporate()
print(f"Current state: {lump.state}")
Debug
Known issues
breakingThe legacy `HierarchicalMachine` implementation was removed in version 0.9.0. Users should migrate to the `NestedState` and `HierarchicalMachine` features available directly via the standard `Machine` class or its `HierarchicalMachine` extension.fixRefactor state machine definitions to use the modern hierarchical state features provided by the main `Machine` class and `NestedState` objects. Review the official documentation for nested state examples.
affects: >=0.9.0
gotchaWhen using `add_transition` with multiple conditional transitions for the same trigger/source, the order in which transitions are added matters. Transitions are evaluated in the order they were added, and the first one whose conditions evaluate to `True` will be executed.fixCarefully order your `add_transition` calls. Place more specific or restrictive conditions before more general ones to ensure the desired transition takes precedence. Consider using the `conditions` argument within a single transition if multiple checks are needed for the same outcome.
affects: All
gotchaWhen `queued=True` is enabled for a `Machine`, trigger calls will always return `True` immediately, as there is no way to determine at queuing time if a transition will ultimately complete successfully after processing the queue.fixWhen working with `queued=True`, do not rely on the return value of trigger methods to indicate immediate success. Instead, rely on callbacks (`on_enter`, `on_exit`, `after`) or monitor the model's state for eventual completion.
affects: All (when `queued=True`)
gotchaMethods assigned as callbacks (e.g., `before`, `after`, `on_enter`, `on_exit`, `conditions`) must be able to handle all arguments that the triggering event passes. This can be problematic if different callbacks expect different data.fixEnsure all callbacks associated with a transition's event are designed to accept the same set of arguments or use `*args` and `**kwargs` to accept arbitrary parameters. Alternatively, create wrapper functions that adapt the arguments for specific callbacks.
affects: All
breakingIn version 0.8.10, the literal string 'self' (the default model parameter of `Machine`) changed from a value check to an identity check. This affects how `Machine` determines if it should act as its own model.fixIf you explicitly passed `model='self'` to `Machine` and relied on a custom object also named 'self', this might break. It is recommended to either pass the actual instance of the object as the model or use `Machine.self_literal` for custom identity checks if you need to override the default behavior.
affects: >=0.8.10
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'transitions'
The 'transitions' library is not installed in the current Python environment or the environment is not activated.
fixpip install transitions
ValueError: State 'invalid_state_name' is not a valid state.
The state specified as the 'initial' state for the machine or as a target state in a transition does not exist in the list of states defined for the Machine.
fixEnsure the state name used matches exactly one of the state names provided in the 'states' argument when initializing the Machine.
transitions.core.MachineError: Can't go from source_state to target_state. No transition exists.
The current model's state does not have a defined transition to the target state for the event being triggered, or a direct 'to()' call was made to a state without an explicit transition path.
fixDefine a transition in the Machine configuration that allows moving from 'source_state' to 'target_state' for the specific event, or ensure a valid event is triggered.
TypeError: on_enter_state() missing 1 required positional argument: 'event'
A callback function (e.g., on_enter_state, on_exit_state, before, after) is defined to expect certain arguments but is being called without them, or with an incorrect number/type of arguments, due to how 'transitions' passes them.
fixAdjust the callback function signature to match the arguments 'transitions' provides (e.g., 'def on_enter_state(self, event):' for an event-bound callback on a model, or 'def on_enter_state(event):' for a state-bound callback) or make arguments optional.
Upgrade
Version history
0.9.3latest on PyPI · released Jul 2, 2025
Audit
Dependencies
No dependency data recorded yet.