Install & Compatibility
Where this runs
tested against v0.81.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 70.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.5s · import 0.000s · 71MB
69MB installed
● package 69MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
unfold
✓ import unfold
✗ unfold
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
Debug
Known issues
breakingPython 3.10 support was dropped in version 0.82.0. Projects using `django-unfold` must be running Python 3.11 or newer.fixUpgrade your Python environment to 3.11 or later. Ensure your `settings.py` includes `requires_python='<4.0,>=3.11'`.
affects: >=0.82.0
gotchaThe '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.fixEnsure `INSTALLED_APPS = ["unfold", "django.contrib.admin", ...]` in your `settings.py`.
affects: All versions
gotchaAll custom `ModelAdmin` classes intended to use Unfold's features must inherit from `unfold.admin.ModelAdmin`, not `django.contrib.admin.ModelAdmin`.fixChange `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):`.
affects: All versions
gotchaAfter 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.fixExecute `python manage.py collectstatic --noinput --clear` after any `pip install --upgrade django-unfold` or initial setup. Clear your browser cache afterwards.
affects: All versions
gotchaExisting 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.fixTest your existing customizations thoroughly in a development environment. Refer to the Unfold documentation for guidance on overriding templates and integrating custom assets.
affects: All versions (when migrating or adding customizations)
Upgrade
Version history
0.104.1latest on PyPI · released Aug 12, 2026
Audit
Dependencies
DjangorequiredUnfold is built entirely on django.contrib.admin and requires Django to function. It explicitly supports Django versions compatible with Python >=3.11, <4.0.