---
id: django-dirtyfields
version: "1.9.9"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# django-dirtyfields — Tracking dirty fields on a Django model instance.

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

## What it is and what it does

Django Dirty Fields is a mixin that tracks in-memory changes to Django model instances, letting you detect which fields differ from their database values without querying the database. You inherit from DirtyFieldsMixin on any model, then call is_dirty() to check if the instance has unsaved changes or get_dirty_fields() to retrieve a dictionary of changed field names and their original values.

This is useful for conditional logic around saves, audit trails, or avoiding unnecessary database writes. The package has been in production use since its early releases and is tested against a wide range of Django and Python versions. It requires only Django as a dependency and installs as a lightweight pure-Python wheel.

Use it for:

- Check if a model instance has unsaved changes before deciding whether to call save().
- Audit which fields were modified on an instance for logging or change-tracking systems.
- Conditionally trigger side effects only when specific fields change.
- Implement undo/rollback logic by comparing dirty fields to their original database values.
- Validate that certain fields have not been modified before allowing a save operation.

## Worth the install?

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

Tracks which fields on a Django model instance have been modified in memory but not yet saved to the database, providing methods to check dirty status and retrieve changed field values.

Yes. The package is production-stable, actively maintained, has no known vulnerabilities, installs with minimal friction, and solves a common Django pattern cleanly. Use it when you need to detect in-memory changes to model instances without extra database queries.

## Install

pip install django-dirtyfields
uv add django-dirtyfields
poetry add django-dirtyfields

## Installing django-dirtyfields

Before you install: Low friction: pure Python wheel with only Django as a runtime dependency. Actively maintained with recent commits and compatible across Django 3.2 through 6.0 and Python 3.10–3.14.

License in practice: BSD-3-Clause permissive license allows commercial and private use with minimal restrictions beyond attribution and liability disclaimers.

Quickstart:

pip install django-dirtyfields

from django.db import models
from dirtyfields import DirtyFieldsMixin

class ExampleModel(DirtyFieldsMixin, models.Model):
    boolean = models.BooleanField(default=True)

model = ExampleModel.objects.create(boolean=True)
model.boolean = False
model.is_dirty()  # True
model.get_dirty_fields()  # {'boolean': True}

## Package facts

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

## Tags

django model change tracking, detect modified fields django, dirty fields mixin, django model dirty state, track unsaved changes django, django-orm, change-tracking

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