{"id":4932,"library":"django-unfold","title":"Django Unfold","description":"Django Unfold is a modern, customizable admin theme for Django, built on top of Tailwind CSS. It enhances the existing `django.contrib.admin` interface with a clean UI, dark mode, advanced navigation, and powerful features, without requiring a complete replacement or database migrations. Actively developed with frequent releases, the current version is 0.89.0.","status":"active","version":"0.89.0","language":"en","source_language":"en","source_url":"https://github.com/unfoldadmin/django-unfold","tags":["Django","admin theme","UI","dashboard","Tailwind CSS","admin panel"],"install":[{"cmd":"pip install django-unfold","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Unfold is built entirely on django.contrib.admin and requires Django to function. It explicitly supports Django versions compatible with Python >=3.11, <4.0.","package":"Django"}],"imports":[{"note":"The 'unfold' app must be listed *before* 'django.contrib.admin' in INSTALLED_APPS for its templates and styles to take precedence.","wrong":"INSTALLED_APPS = [\n    \"django.contrib.admin\",\n    \"unfold\",\n    # ... other apps\n]","symbol":"unfold","correct":"# settings.py\nINSTALLED_APPS = [\n    \"unfold\",\n    \"django.contrib.admin\",\n    # ... other apps\n]"},{"note":"To apply Unfold's styling and functionality, your admin classes must inherit from `unfold.admin.ModelAdmin` instead of the default Django `ModelAdmin`.","wrong":"from django.contrib.admin import ModelAdmin","symbol":"ModelAdmin","correct":"from unfold.admin import ModelAdmin"}],"quickstart":{"code":"import os\n\n# settings.py\nSECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'your-insecure-secret-key-for-dev')\nDEBUG = os.environ.get('DJANGO_DEBUG', 'True').lower() == 'true'\n\nINSTALLED_APPS = [\n    \"unfold\", # Must be before django.contrib.admin\n    \"django.contrib.admin\",\n    \"django.contrib.auth\",\n    \"django.contrib.contenttypes\",\n    \"django.contrib.sessions\",\n    \"django.contrib.messages\",\n    \"django.contrib.staticfiles\",\n    # Your apps here\n]\n\n# urls.py\nfrom django.contrib import admin\nfrom django.urls import path\n\nurlpatterns = [\n    path('admin/', admin.site.urls),\n]\n\n# myapp/admin.py\nfrom django.contrib import admin\nfrom unfold.admin import ModelAdmin\nfrom .models import MyModel\n\n@admin.register(MyModel)\nclass MyModelAdmin(ModelAdmin):\n    list_display = ('name', 'created_at')\n    search_fields = ('name',)\n\n# myapp/models.py\nfrom django.db import models\n\nclass MyModel(models.Model):\n    name = models.CharField(max_length=255)\n    description = models.TextField(blank=True)\n    created_at = models.DateTimeField(auto_now_add=True)\n\n    def __str__(self):\n        return self.name\n","lang":"python","description":"After installing `django-unfold`, add `\"unfold\"` to your `INSTALLED_APPS` list *before* `\"django.contrib.admin\"`. Then, ensure your `ModelAdmin` classes inherit from `unfold.admin.ModelAdmin`. Run `python manage.py collectstatic` to gather Unfold's static files."},"warnings":[{"fix":"Upgrade your Python environment to 3.11 or later. Ensure your `settings.py` includes `requires_python='<4.0,>=3.11'`.","message":"Python 3.10 support was dropped in version 0.82.0. Projects using `django-unfold` must be running Python 3.11 or newer.","severity":"breaking","affected_versions":">=0.82.0"},{"fix":"Ensure `INSTALLED_APPS = [\"unfold\", \"django.contrib.admin\", ...]` in your `settings.py`.","message":"The 'unfold' application must be placed before 'django.contrib.admin' in your `INSTALLED_APPS` list. Incorrect placement will result in unstyled forms and missing Unfold functionality.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Change `from django.contrib import admin` to `from unfold.admin import ModelAdmin` and update your admin class definitions, e.g., `@admin.register(MyModel) class MyModelAdmin(ModelAdmin):`.","message":"All custom `ModelAdmin` classes intended to use Unfold's features must inherit from `unfold.admin.ModelAdmin`, not `django.contrib.admin.ModelAdmin`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Execute `python manage.py collectstatic --noinput --clear` after any `pip install --upgrade django-unfold` or initial setup. Clear your browser cache afterwards.","message":"After installation or upgrade, you should always run `python manage.py collectstatic --clear` to ensure all static files are correctly collected and cached versions are purged.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Test your existing customizations thoroughly in a development environment. Refer to the Unfold documentation for guidance on overriding templates and integrating custom assets.","message":"Existing custom admin templates, CSS, or JavaScript may require adjustments to align with Unfold's structure and Tailwind CSS framework. While many customizations work, some might break or need updates for Unfold's class names.","severity":"gotcha","affected_versions":"All versions (when migrating or adding customizations)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}