{"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":"python","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,"search_vec":"'3.11.0':46 'activ':38 'admin':34,51 'allow':25 'audit':49 'chang':31 'current':43 'django':1,5,10,23,47 'django-simple-histori':4 'easi':15 'frequent':41 'histor':19 'histori':3,7,48 'librari':11 'maintain':39 'model':24,50 'provid':13 'record':20 'releas':42 'revert':30 'simpl':2,6 'site':35 'store':18 'version':45 'view':28 'way':16","created_at":"2026-04-11T01:29:59.798709+00:00","updated_at":"2026-04-16T14:35:09.526737+00:00","problems":[{"fix":"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.","cause":"The 'django-simple-history' package is either not installed in the active Python environment or is installed in a different environment than the one Django is using.","error":"ModuleNotFoundError: No module named 'simple_history'"},{"fix":"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.","cause":"Django-simple-history relies on `post_save` signals to record history. Bulk operations like `bulk_create` and `QuerySet.update()` do not emit these signals, so history is not automatically saved.","error":"Django Simple History not recording changes for bulk_create or queryset.update()"},{"fix":"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.","cause":"Historical records and the `HistoryManager` are not regular model instances or managers; they represent a specific past state or a collection of historical states. Direct access to related objects or certain `_meta` attributes may not be available or function as expected.","error":"AttributeError: 'HistoryManager' object has no attribute '_meta' / AttributeError: 'Historical<ModelName>' object has no attribute '<related_field>'"},{"fix":"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)`.","cause":"This error often occurs when `SimpleHistoryAdmin` is incorrectly registered or subclassed, leading Django to try and treat `SimpleHistoryAdmin` itself as a model with `_meta` attributes. This can happen if you pass `SimpleHistoryAdmin` directly to `admin.site.register()` without a model, or if there's an issue in your `admin.py` with how you define or register your admin classes.","error":"AttributeError: type object 'SimpleHistoryAdmin' has no attribute '_meta'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.13.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/django-commons/django-simple-history","docs":"https://django-simple-history.readthedocs.io/en/stable/","changelog":"https://github.com/django-commons/django-simple-history/blob/master/CHANGES.rst","pypi":"https://pypi.org/project/django-simple-history/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}