Django Unfold

0.89.0 · active · verified Sun Apr 12

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.

Warnings

breaking Python 3.10 support was dropped in version 0.82.0. Projects using `django-unfold` must be running Python 3.11 or newer.
Fix: Upgrade your Python environment to 3.11 or later. Ensure your `settings.py` includes `requires_python='<4.0,>=3.11'`.
gotcha 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.
Fix: Ensure `INSTALLED_APPS = ["unfold", "django.contrib.admin", ...]` in your `settings.py`.
gotcha All custom `ModelAdmin` classes intended to use Unfold's features must inherit from `unfold.admin.ModelAdmin`, not `django.contrib.admin.ModelAdmin`.
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):`.
gotcha 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.
Fix: Execute `python manage.py collectstatic --noinput --clear` after any `pip install --upgrade django-unfold` or initial setup. Clear your browser cache afterwards.
gotcha 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.
Fix: Test your existing customizations thoroughly in a development environment. Refer to the Unfold documentation for guidance on overriding templates and integrating custom assets.

Install

pip install django-unfold Install latest version

Imports

unfold
```
# settings.py
INSTALLED_APPS = [
    "unfold",
    "django.contrib.admin",
    # ... other apps
]
```
The 'unfold' app must be listed *before* 'django.contrib.admin' in INSTALLED_APPS for its templates and styles to take precedence.
ModelAdmin
```
from unfold.admin import ModelAdmin
```
To apply Unfold's styling and functionality, your admin classes must inherit from `unfold.admin.ModelAdmin` instead of the default Django `ModelAdmin`.

Quickstart

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.

import os

# settings.py
SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'your-insecure-secret-key-for-dev')
DEBUG = os.environ.get('DJANGO_DEBUG', 'True').lower() == 'true'

INSTALLED_APPS = [
    "unfold", # Must be before django.contrib.admin
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # Your apps here
]

# urls.py
from django.contrib import admin
from django.urls import path

urlpatterns = [
    path('admin/', admin.site.urls),
]

# myapp/admin.py
from django.contrib import admin
from unfold.admin import ModelAdmin
from .models import MyModel

@admin.register(MyModel)
class MyModelAdmin(ModelAdmin):
    list_display = ('name', 'created_at')
    search_fields = ('name',)

# myapp/models.py
from django.db import models

class MyModel(models.Model):
    name = models.CharField(max_length=255)
    description = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name

view raw JSON →