---
id: django-fsm-log
version: "5.0.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# django-fsm-log — Transition's persistence for django-fsm

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

## What it is and what it does

django-fsm-log is a Django app that automatically captures and persists state machine transitions for models using django-fsm-2. It listens for FSM transition signals and creates database records for each state change, including source state, target state, timestamp, and optional metadata like the user who triggered the transition.

The package provides query helpers (StateLog.objects.for_() to filter by model instance), decorators to attach user information or custom descriptions to transitions, and admin integration to visualize transition history. It can optionally cache pending transitions before they're persisted, allowing access to log details immediately after a transition begins rather than waiting for database commit.

Use it for:

- Track approval workflows in document management systems, logging who approved/rejected and when.
- Audit state changes in order processing pipelines for compliance and debugging.
- Display transition history in Django admin to show users how a model's state evolved.
- Implement rollback or undo features by querying the StateLog to find previous states.
- Generate reports on transition timing and frequency to identify bottlenecks in workflows.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Automatically logs state transitions for Django FSM models to the database, capturing the source state, target state, timestamp, and optional metadata like the user who triggered the transition.

Yes. The package is actively maintained, supports current Django and Python versions, has no known vulnerabilities, and solves a common need for FSM-based Django applications. Install it if you're using django-fsm-2 and need to audit or display state transition history; the low install friction and permissive license make it a straightforward addition.

## Install

pip install django-fsm-log
uv add django-fsm-log
poetry add django-fsm-log

## Installing django-fsm-log

Before you install: Low friction installation with three straightforward dependencies (django, django-fsm-2, django-appconf). The package is actively maintained with recent releases supporting modern Django versions (5.2, 6.0) and Python 3.14, indicating ongoing compatibility work.

License in practice: MIT license is permissive, allowing use in commercial and open-source projects with minimal restrictions—only requiring attribution.

Quickstart:

pip install django-fsm-log

# Add to INSTALLED_APPS
INSTALLED_APPS = (..., 'django_fsm_log', ...)

# Run migrations
python manage.py migrate django_fsm_log

# Query logs
from django_fsm_log.models import StateLog
StateLog.objects.all()

Requires an existing Django project with django-fsm-2 already configured; the package listens for django_fsm.signals.post_transition, so FSM models must be set up first.

Verify before relying:

- Whether the cached backend feature (CachedBackend) is suitable for high-concurrency scenarios or has known limitations.
- Performance impact when logging transitions for models with very high transition frequency.
- Whether the admin integration (StateLogInline) works with all Django admin customizations.

## Package facts

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

## Tags

django fsm logging, state machine transition history, django workflow audit trail, fsm state change tracking, django model state log, transition persistence django, django-orm, audit-trail, state-machine

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