django-auditlog

django-auditlog (Auditlog) is a reusable Django app that keeps a detailed log of changes made to your models. It automatically records every create, update, and delete operation, stores a JSON summary of exactly which fields changed, and captures the user (actor) responsible for the change.

Built to lean heavily on Django’s own signals and ORM, Auditlog keeps its dependency footprint small while staying fast and simple to wire in. Rather than offering heavyweight version control, it provides a lightweight, queryable history that is inexpensive to store and easy to reason about.

What You Get

• A LogEntry model that stores create/update/delete history with a JSON field-level diff
• One-line model registration via auditlog.register() or the AuditlogModelRegistry
• Middleware that automatically attaches the acting user to each change
• An AuditlogHistoryField and admin/template integration for surfacing history in your UI

Common Use Cases

• Maintaining a compliance or accountability trail of data changes in business applications
• Debugging by seeing exactly which field changed, to what value, and by which user
• Surfacing per-object change history inside the Django admin or custom dashboards

Under The Hood

Architecture - The core is an AuditlogModelRegistry (registry.py) that connects each tracked model to Django’s pre_save, post_save, post_delete, and m2m_changed signals; receivers.py handles the signal callbacks, models.py’s LogEntryManager builds a serialized JSON diff of changed fields via diff.py, and middleware.py stashes the acting user in a thread-local context so receivers can attribute each change. AuditlogHistoryField exposes the history as a GenericRelation.

Tech Stack - Pure Python targeting Python 3.10+ and Django 4.2+, with python-dateutil as its only runtime dependency. Packaging uses setuptools with setuptools_scm for version derivation; formatting and imports are handled by black and isort, with pre-commit and tox wiring CI across Django and Python matrices.

Code Quality - The codebase is small, typed with modern annotations, and well factored across single-responsibility modules (registry, receivers, diff, models, middleware). A dedicated auditlog_tests project with multiple test modules, tox matrices, and Codecov reporting backs it, and the project maintains a detailed CHANGELOG and localized message catalogs.

API Design - The public surface is deliberately minimal and ergonomic: register a model with a single auditlog.register() call (optionally scoping included/excluded fields), add AuditlogMiddleware for actor capture, and read history through the LogEntry model or AuditlogHistoryField. Comprehensive Read the Docs documentation and an explicit v3 upgrade guide keep onboarding low-friction.