Django Simple History

3.11.0 · active · verified Fri Apr 10

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.

Warnings

breaking The `simple_history_admin_list.display_list()` method was removed. If you were using this for custom admin views, it will break.
Fix: 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`.
breaking Support for Django 3.2 has been officially dropped. Projects using django-simple-history 3.7.0 or newer must upgrade their Django version.
Fix: Upgrade your Django project to version 3.6 or newer. For versions 3.7.0+, Django 3.2 is no longer supported.
gotcha When defining `HistoricalRecords`, it must be instantiated (e.g., `history = HistoricalRecords()`). Forgetting the parentheses is a common error.
Fix: 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.
gotcha Historical records for Many-to-Many (M2M) relationships require specific handling and are not tracked by default with simple `HistoricalRecords()`. Support for M2M with inheritance and signals was improved in 3.3.0.
Fix: 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.
gotcha The repository moved from 'jazzband' to 'django-commons'. While not a direct code-breaking change, old documentation links, issue trackers, or GitHub references might be outdated.
Fix: Ensure you are referencing the correct GitHub repository (`github.com/django-commons/django-simple-history`) for up-to-date information, issues, and contributions.

Install

pip install django-simple-history Install stable version

Imports

HistoricalRecords
```
from simple_history.models import HistoricalRecords
```
HistoricalRecords is defined within the models submodule.
SimpleHistoryAdmin
```
from simple_history.admin import SimpleHistoryAdmin
```
SimpleHistoryAdmin is specifically for integrating with Django's admin interface.
register
```
from simple_history import register
```
The top-level `register` function for dynamic model registration is directly under the simple_history package.

Quickstart

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`.

import os
from django.db import models
from simple_history.models import HistoricalRecords

# Ensure 'simple_history' is in INSTALLED_APPS in your Django settings.
# Example: INSTALLED_APPS = ['...', 'simple_history', 'myapp']

class Product(models.Model):
    name = models.CharField(max_length=200)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    history = HistoricalRecords()

    def __str__(self):
        return self.name

# To see history in the Django admin:
# 1. Add 'simple_history' to INSTALLED_APPS.
# 2. In myapp/admin.py:
#    from django.contrib import admin
#    from simple_history.admin import SimpleHistoryAdmin
#    from .models import Product
#    admin.site.register(Product, SimpleHistoryAdmin)

view raw JSON →