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

Provides finite state machine support for Django models, allowing you to define states and controlled transitions between them using decorators and enums.

Yes, with conditions. The package is stable and permissively licensed, with no known vulnerabilities and low install friction. However, the aging maintenance status (311 days since last release, marked inactive) and the breaking API change in version 3.0 mean you should verify that the current version meets your Django and Python requirements and that you're comfortable with limited active development.

Install

django-fsm on PyPI

pip install django-fsm

uv add django-fsm

poetry add django-fsm

Installing django-fsm

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

Verify before relying

• Whether version 3.0.1 is a breaking change from 2.x and what migration effort is required.
• Current maintenance timeline and whether aging status signals end-of-life or stable maintenance.
• Minimum Python and Django version requirements not explicitly stated in metadata.

Package facts

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

Keywords: django

Tags

More Python Modules packages