django-simple-history is a Django library that provides an easy way to store historical records for your Django models, allowing you to view and revert changes through the admin site. It is actively maintained with frequent releases, currently at version 3.11.0.
pip install django-simple-historyVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to add historical tracking to a Django model by simply adding a `history = HistoricalRecords()` field. Remember to add `simple_history` to your `INSTALLED_APPS` and run `makemigrations`/`migrate`. For admin integration, register your model with `SimpleHistoryAdmin`.
Review your admin customizations and update them to use current Django admin patterns or alternative methods for displaying history lists. Consult the official documentation for `SimpleHistoryAdmin`.
Upgrade your Django project to version 3.6 or newer. For versions 3.7.0+, Django 3.2 is no longer supported.
Always use `HistoricalRecords()` with parentheses. If you use `HistoricalRecords` without them, it will result in incorrect behavior or errors as you're assigning the class itself, not an instance.
For M2M history, you generally need to track changes on the 'through' model or implement custom logic. Refer to the official `django-simple-history` documentation on 'Historical Many-to-Many' relationships for detailed guidance.
Ensure you are referencing the correct GitHub repository (`github.com/django-commons/django-simple-history`) for up-to-date information, issues, and contributions.
Ensure the library is installed using pip: `pip install django-simple-history` and that your virtual environment is activated and correctly configured for your project.
For `bulk_create`, use `simple_history.utils.bulk_create_with_history`. For `QuerySet.update()`, iterate over the queryset and call `save()` on each instance, or use a custom utility function that manually creates historical records.
To access related objects from a historical record, you usually need to retrieve the actual instance using `historical_record.instance` first, or specifically define `HistoricForeignKey` or `HistoricOneToOneField` if relationships need to be honored at a historical point in time.
Ensure `SimpleHistoryAdmin` is used as a mixin or directly inherited by your model's admin class, and that it's correctly registered with your model. For example: `from simple_history.admin import SimpleHistoryAdmin; @admin.register(MyModel) class MyModelAdmin(SimpleHistoryAdmin): pass` or `admin.site.register(MyModel, MyModelAdmin)`.