---
id: transitions
version: "0.9.3"
license: MIT
license_treatment: permissive
maintenance: aging
---

# transitions — A lightweight, object-oriented Python state machine implementation with many extensions.

License: permissive · Maintenance: aging · Downloads: 2.9M/mo

## What it is and what it does

Transitions is a state machine library that embeds finite-state behavior into Python objects. You define states and transitions between them, then attach the machine to a model object; the library automatically creates trigger methods that move the object between states. It supports callbacks (actions executed before, after, or during transitions), conditional transitions, and wildcard source states.

The library is designed for modeling workflows, event-driven systems, and stateful processes where you need to enforce valid state changes and execute side effects when transitions occur. It's built on top of six for Python 2/3 compatibility and has a minimal dependency footprint.

Use it for:

- Model application workflows where objects move through defined states (e.g., order processing: pending → shipped → delivered).
- Implement event-driven systems where triggers initiate state changes and callbacks execute business logic.
- Build game or simulation logic where entities have discrete states and rules governing transitions between them.
- Enforce state validity in domain objects by preventing invalid transitions and logging state changes.
- Create interactive state machines for chatbots, form wizards, or multi-step processes.

## Worth the install?

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

Transitions is a lightweight state machine library that lets you attach finite-state behavior to Python objects, with support for states, transitions, triggers, and callbacks.

Yes, if you need a straightforward state machine for modeling workflows or stateful behavior. The library is stable, permissively licensed, and has low install friction. However, note that maintenance is aging (last release July 2025, no recent commits); if you require active development or frequent updates, verify that the project's pace aligns with your needs. No known security vulnerabilities.

## Install

pip install transitions
uv add transitions
poetry add transitions

## Installing transitions

Before you install: Low install friction; pure Python wheel with only six as a runtime dependency. Maintenance status is aging—last release was 2025-07-02 and the repository shows no recent activity, though it remains unarchived with a substantial GitHub presence.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

from transitions import Machine

class Matter:
    pass

lump = Matter()
machine = Machine(model=lump, states=['solid', 'liquid'], initial='solid')
machine.add_transition(trigger='melt', source='solid', dest='liquid')
lump.melt()  # Triggers transition
print(lump.state)  # 'liquid'

Verify before relying:

- Whether the aging maintenance status (last release 2025-07-02, no recent commits) affects stability or security for new projects.
- Whether extensions mentioned in the description (e.g., Diagrams) are included or require separate installation.

## Package facts

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

## Tags

state machine library python, finite state machine implementation, object state management, workflow state transitions, event-driven state changes, state-machine, workflow-engine, event-driven

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