django-fsm-2

What it is and what it does

Django FSM-2 is a maintained fork of the archived Django FSM project that brings finite state machine patterns to Django models. Instead of storing state as a plain CharField and managing transitions scattered throughout your codebase, you declare states and transitions once using decorators on model methods. This centralizes your model's lifecycle logic in one place, making it easier to reason about valid state changes, enforce preconditions, and attach business logic (side effects, permissions, notifications) to specific transitions.

The package works by providing FSMField (or FSMIntegerField/FSMKeyField variants) to store state, the @transition decorator to define allowed state changes, and helper methods to check permissions and available transitions. Transition methods can contain arbitrary logic; the state changes in memory on success, and you persist it with save(). You can restrict transitions with conditions, attach permissions, specify error-handling states, and use dynamic target states based on method return values.

Use it for

• Managing blog post lifecycle (draft → review → published → archived) with automatic permission and timing checks.
• Enforcing order state workflows (pending → processing → shipped → delivered) with side effects like notifications.
• Controlling document approval flows where transitions require specific user permissions and conditions.
• Building task or ticket systems where state changes trigger notifications or log entries.
• Implementing subscription or account status transitions with business logic tied to each change.

Worth the install?

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

Install

django-fsm-2 on PyPI

Before you install

Low friction install with only three runtime dependencies (django, django-stubs-ext, typing-extensions). The package is actively maintained with a recent commit on 2026-08-07 and marked as Production/Stable.

Requires Python 3.10 or later and Django 4.2 or later.

License in practice

MIT license (permissive) means you can use this freely in commercial and private projects with minimal restrictions.

Quickstart

pip install django-fsm-2

from django_fsm import FSMField, FSMModelMixin, transition

class BlogPost(FSMModelMixin, models.Model):
    state = FSMField(default='new')
    
    @transition(field=state, source='new', target='published')
    def publish(self, **kwargs):
        pass

post = BlogPost.objects.get(pk=1)
post.publish()
post.save()

Package facts

Evidence: django_fsm_2-4.2.4-py3-none-any.whl

Tags

More Python Modules packages

See also automaton · django-fsm · django-fsm-log · django-lifecycle · python-statemachine · fysom · transitions · django-pgtrigger · Automat · django-concurrency