{"id":2482,"library":"django-simple-history","title":"Django Simple History","description":"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.","status":"active","version":"3.11.0","language":"en","source_language":"en","source_url":"https://github.com/django-commons/django-simple-history","tags":["django","history","auditing","models","admin"],"install":[{"cmd":"pip install django-simple-history","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core framework dependency; requires Django>=3.2.","package":"Django","optional":false}],"imports":[{"note":"HistoricalRecords is defined within the models submodule.","wrong":"from simple_history import HistoricalRecords","symbol":"HistoricalRecords","correct":"from simple_history.models import HistoricalRecords"},{"note":"SimpleHistoryAdmin is specifically for integrating with Django's admin interface.","wrong":"from simple_history.models import SimpleHistoryAdmin","symbol":"SimpleHistoryAdmin","correct":"from simple_history.admin import SimpleHistoryAdmin"},{"note":"The top-level `register` function for dynamic model registration is directly under the simple_history package.","wrong":"from simple_history.models import register","symbol":"register","correct":"from simple_history import register"}],"quickstart":{"code":"import os\nfrom django.db import models\nfrom simple_history.models import HistoricalRecords\n\n# Ensure 'simple_history' is in INSTALLED_APPS in your Django settings.\n# Example: INSTALLED_APPS = ['...', 'simple_history', 'myapp']\n\nclass Product(models.Model):\n    name = models.CharField(max_length=200)\n    price = models.DecimalField(max_digits=10, decimal_places=2)\n    history = HistoricalRecords()\n\n    def __str__(self):\n        return self.name\n\n# To see history in the Django admin:\n# 1. Add 'simple_history' to INSTALLED_APPS.\n# 2. In myapp/admin.py:\n#    from django.contrib import admin\n#    from simple_history.admin import SimpleHistoryAdmin\n#    from .models import Product\n#    admin.site.register(Product, SimpleHistoryAdmin)\n","lang":"python","description":"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`."},"warnings":[{"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`.","message":"The `simple_history_admin_list.display_list()` method was removed. If you were using this for custom admin views, it will break.","severity":"breaking","affected_versions":">=3.9.0"},{"fix":"Upgrade your Django project to version 3.6 or newer. For versions 3.7.0+, Django 3.2 is no longer supported.","message":"Support for Django 3.2 has been officially dropped. Projects using django-simple-history 3.7.0 or newer must upgrade their Django version.","severity":"breaking","affected_versions":">=3.7.0"},{"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.","message":"When defining `HistoricalRecords`, it must be instantiated (e.g., `history = HistoricalRecords()`). Forgetting the parentheses is a common error.","severity":"gotcha","affected_versions":"<all>"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<all>"},{"fix":"Ensure you are referencing the correct GitHub repository (`github.com/django-commons/django-simple-history`) for up-to-date information, issues, and contributions.","message":"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.","severity":"gotcha","affected_versions":">=3.10.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}