Django Audit Log

3.4.1 · active · verified Sun Apr 12

django-auditlog is a pluggable Django app that provides audit logging functionality for your models. It automatically tracks changes to model instances (create, update, delete actions), recording who made the change, when, and what changed. The current version is 3.4.1, and the project maintains an active release cadence with frequent updates to support new Django and Python versions.

Warnings

breaking Python 3.9 support was dropped.
Fix: Ensure your project uses Python 3.10 or newer (Python 3.10 is the minimum requirement for django-auditlog v3.4.0+).
breaking Django 4.1 support was dropped.
Fix: Upgrade your Django project to Django 4.2 or newer. Django 4.2 is the minimum requirement for django-auditlog v3.0.0+.
breaking Log entry deletion behavior when primary keys are reused changed. Previously, if a model instance was deleted and a new instance was created with the same primary key, old log entries for that PK might have been deleted. This no longer happens.
Fix: Be aware that historical log entries will now persist even if their original object's PK is reused. This is generally a safer default, preventing unintended data loss in audit trails.
gotcha For Django 4.2+ environments, `thread.local` for context management was replaced with `ContextVar`. This is an internal change but might affect custom integrations that relied on `thread.local` for actor context propagation outside of the standard `AuditlogMiddleware`.
Fix: If experiencing issues with actor tracking in complex or asynchronous environments on Django 4.2+, review your custom context handling or ensure `AuditlogMiddleware` is correctly in place.
gotcha Actor tracking (who performed the action) will result in `null` `actor` fields in `LogEntry` if `auditlog.middleware.AuditlogMiddleware` is not properly enabled in `MIDDLEWARE` in your `settings.py`, or if `auditlog.context.set_actor()` is not manually called.
Fix: Always include `auditlog.middleware.AuditlogMiddleware` in your Django `MIDDLEWARE` settings. For custom scenarios (e.g., management commands or Celery tasks), use `auditlog.context.set_actor(user)` manually.
gotcha The `AUDITLOG_STORE_JSON_CHANGES` setting (introduced in v3.2.0) allows storing changes as JSON. Early versions (v3.2.0 to v3.2.1) had issues with updates/deletes and the `changes_display_dict` when this setting was `True`.
Fix: If you plan to use `AUDITLOG_STORE_JSON_CHANGES = True`, ensure you are on version `3.3.0` or newer for full stability and correct `changes_display_dict` behavior.

Install

pip install django-auditlog Install stable version

Imports

auditlog
```
from auditlog.registry import auditlog
```
This imports the main registry instance used to register models for auditing.
LogEntry
```
from auditlog.models import LogEntry
```
This is the model used to query and view audit logs.

Quickstart

To get started with django-auditlog: 1. Add 'auditlog' to your `INSTALLED_APPS` in `settings.py`. 2. Add 'auditlog.middleware.AuditlogMiddleware' to your `MIDDLEWARE` list in `settings.py` (essential for 'actor' tracking). 3. Run `python manage.py makemigrations` and `python manage.py migrate` to create the `LogEntry` table. 4. Place the provided code snippet in your app's `models.py` (or similar location) to register `MyAuditedModel`. Once set up, any creates, updates, or deletes on `MyAuditedModel` instances will automatically generate `LogEntry` records. You can then query `LogEntry.objects` or use the Django Admin to view the audit trail.

from django.db import models
from auditlog.registry import auditlog

class MyAuditedModel(models.Model):
    name = models.CharField(max_length=255)
    description = models.TextField(blank=True)
    
    def __str__(self):
        return self.name

    class Meta:
        app_label = 'myapp' # Replace 'myapp' with your actual app name

# Register the model for audit logging
auditlog.register(MyAuditedModel)

view raw JSON →