Django Easy Audit

1.3.8 verified Fri May 01 auth: no python

Yet another Django audit log app, logging login attempts, CRUD events, and requests. Version 1.3.8 is latest stable, compatible with Django 4.2–5.2 and Python 3.9–3.13. Pre-releases (1.3.9.a2) add Django 6.0 and Python 3.14 support. Regular releases about every 6 months.

pip install django-easy-audit

Common errors

error django.core.exceptions.ImproperlyConfigured: Cannot import 'easy_audit'. Check that 'easy_audit' is in INSTALLED_APPS. ↓

cause The Python package is 'easy_audit', not 'django_easy_audit'. Common mistake to use the PyPI name.

fix

Add 'easy_audit' to INSTALLED_APPS (not 'django-easy-audit').

error KeyError: 'REMOTE_ADDR' ↓

cause Your Django server is behind a reverse proxy that does not set REMOTE_ADDR. Fixed in v1.3.6+ with optional REMOTE_ADDR.

fix

Upgrade to v1.3.6 or later. If already upgraded, ensure the middleware is after CommonMiddleware.

error ModuleNotFoundError: No module named 'easy_audit' ↓

cause The package is not installed or installed under a different name. 'pip install django-easy-audit' installs the package with module name 'easy_audit'.

fix

Run 'pip install django-easy-audit' again. Check that the module name is 'easy_audit' not 'django_easy_audit'.

Warnings

breaking In v1.3.7, support for Django 3.2 was dropped. If you upgrade from an older version and use Django 3.2, your app will break. ↓

fix Upgrade Django to 4.2 or later.

gotcha If you use a custom user model, you must ensure it has an id field. The library assumes user.id is integer. Assigning an anonymous user returns None for user_id. ↓

fix Make sure your user model's id field is an integer or adjust the library's signal handlers.

deprecated The setting `DJANGO_EASY_AUDIT_CRUD_EVENT_IGNORED_FIELDS` is deprecated in favor of `DJANGO_EASY_AUDIT_CRUD_EVENT_EXCLUDED_FIELDS`. Using the old name still works but may be removed in future. ↓

fix Rename to `DJANGO_EASY_AUDIT_CRUD_EVENT_EXCLUDED_FIELDS` in settings.

gotcha The middleware may not work with ASGI/async views out of the box. Async support was added in v1.3.8.b1 but may still have edge cases. ↓

fix Upgrade to v1.3.8 or later. If still issues, wrap with `sync_to_async`.

gotcha If you set `DJANGO_EASY_AUDIT_CRUD_DIFFERENCE_CALLBACKS`, the callbacks must be importable strings (e.g., 'module.function'). If the callback raises an exception, the audit log entry may not be created. ↓

fix Wrap custom callbacks in try/except to avoid breaking the audit.

Imports

EasyAuditMiddleware

wrong

from django_easy_audit.middleware import EasyAuditMiddleware

correct

from easy_audit.middleware import EasyAuditMiddleware

Package name on PyPI is django-easy-audit but the Python package is easy_audit.

CRUDEvent

wrong

from easy_audit.models import C R U D E v e n t

correct

from easy_audit.models import CRUDEvent

Common typo: wrong casing or spaces.

RequestEvent

from easy_audit.models import RequestEvent

LoginAttempt

from easy_audit.models import LoginAttempt

logout_signal

from easy_audit.signals import logout_signal

Quickstart

Add 'easy_audit' to INSTALLED_APPS and the middleware to MIDDLEWARE. Run migrate to create tables.

INSTALLED_APPS = [
    ...
    'easy_audit',
]

MIDDLEWARE = [
    ...
    'easy_audit.middleware.EasyAuditMiddleware',
]

# Then run:
# python manage.py migrate easy_audit
# python manage.py runserver