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

Adds declarative finite state machine support to Django models, letting you define state transitions once with decorators instead of managing state values manually throughout your code.

Yes. This is a well-maintained, actively developed fork of a proven library with no known vulnerabilities, low install friction, and clear production-stable status. Use it if you need to manage model state transitions declaratively in Django; it eliminates scattered state-management code and makes workflows explicit and testable.

Install

django-fsm-2 on PyPI

pip install django-fsm-2

uv add django-fsm-2

poetry add django-fsm-2

Installing django-fsm-2

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.

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()

Requires Python 3.10 or later and Django 4.2 or later.

Verify before relying

• Whether typing support is fully implemented or still planned as mentioned in the description.
• Performance characteristics when managing models with many possible state transitions.

Package facts

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

Tags

More Python Modules packages