{"id":4348,"library":"django-auditlog","title":"Django Audit Log","description":"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.","status":"active","version":"3.4.1","language":"en","source_language":"en","source_url":"https://github.com/jazzband/django-auditlog","tags":["django","auditlog","logging","history","tracking"],"install":[{"cmd":"pip install django-auditlog","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core framework dependency for this app.","package":"Django","optional":false}],"imports":[{"note":"This imports the main registry instance used to register models for auditing.","symbol":"auditlog","correct":"from auditlog.registry import auditlog"},{"note":"This is the model used to query and view audit logs.","symbol":"LogEntry","correct":"from auditlog.models import LogEntry"}],"quickstart":{"code":"from django.db import models\nfrom auditlog.registry import auditlog\n\nclass MyAuditedModel(models.Model):\n    name = models.CharField(max_length=255)\n    description = models.TextField(blank=True)\n    \n    def __str__(self):\n        return self.name\n\n    class Meta:\n        app_label = 'myapp' # Replace 'myapp' with your actual app name\n\n# Register the model for audit logging\nauditlog.register(MyAuditedModel)","lang":"python","description":"To get started with django-auditlog:\n1.  Add 'auditlog' to your `INSTALLED_APPS` in `settings.py`.\n2.  Add 'auditlog.middleware.AuditlogMiddleware' to your `MIDDLEWARE` list in `settings.py` (essential for 'actor' tracking).\n3.  Run `python manage.py makemigrations` and `python manage.py migrate` to create the `LogEntry` table.\n4.  Place the provided code snippet in your app's `models.py` (or similar location) to register `MyAuditedModel`.\nOnce 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."},"warnings":[{"fix":"Ensure your project uses Python 3.10 or newer (Python 3.10 is the minimum requirement for django-auditlog v3.4.0+).","message":"Python 3.9 support was dropped.","severity":"breaking","affected_versions":">=3.4.0"},{"fix":"Upgrade your Django project to Django 4.2 or newer. Django 4.2 is the minimum requirement for django-auditlog v3.0.0+.","message":"Django 4.1 support was dropped.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.4.1 (and any version if misconfigured)"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"3.2.0, 3.2.1"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}