django-fsm

What it is and what it does

django-fsm is a finite state machine library for Django that lets you declare states and transitions declaratively using Python enums and decorators. Instead of allowing arbitrary state changes, it enforces a controlled workflow where transitions between states are explicitly defined and validated. You define a State field with an enum, then attach transition methods decorated with source and target states; calling a transition method moves the state forward only if the transition is allowed, otherwise it raises an exception.

The package is designed for low-level, database-independent FSM logic or as a wrapper around existing Django models to implement persistent workflow processes. It has been in development since 2010, with a major API redesign in version 3.0 that is incompatible with earlier versions. The library provides a simple way to enforce business rules around state changes without building custom validation logic.

Use it for

• Define multi-step approval workflows (e.g., draft → review → approved → published) with controlled transitions.
• Implement order or payment state machines with validation rules and restricted state changes.
• Build task or ticket lifecycle management where state changes are restricted by business logic.
• Create document workflows with states like new, in-review, rejected, and finalized.
• Enforce state-based permissions so only certain transitions are allowed from each state.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

django-fsm on PyPI

Before you install

Low install friction with no runtime dependencies. Maintenance status is aging—last release was 311 days ago and the package is marked as inactive in development status, though the repository remains active with 2349 stars.

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute the package freely with minimal restrictions.

Quickstart

from enum import Enum
from django_fsm import State

class Stage(Enum):
    NEW = 1
    DONE = 2

class MyFlow(object):
    state = State(Stage, default=Stage.NEW)
    
    @state.transition(source=Stage.NEW, target=Stage.DONE)
    def complete(self):
        pass

flow = MyFlow()
flow.complete()  # Transition to DONE

Package facts

Evidence: django_fsm-3.0.1-py2.py3-none-any.whl

Tags

More Python Modules packages

See also django-fsm-2 · django-viewflow · django-fsm-log · automaton · fysom · transitions · python-statemachine · django-dirtyfields · Automat