---
id: django-fsm-2
version: "4.2.4"
license: MIT
license_treatment: permissive
maintenance: active
---

# django-fsm-2 — Django friendly finite state machine support.

License: permissive · Maintenance: active · Downloads: 437.2K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 437.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

django state machine, finite state machine django, django model lifecycle, django workflow transitions, django state transitions, fsm django models, django state management, django-plugin, state-machine, workflow

[View on SkillFed](https://skillfed.io/packages/django-fsm-2) · [View on PyPI](https://pypi.org/project/django-fsm-2/)