Skip to main content
This guide covers common issues you may encounter while using Django Unfold and their solutions.

​
Installation Issues

​
Unfold Not Appearing

Ensure "unfold" is placed before "django.contrib.admin" in your INSTALLED_APPS.
Problem: After installing Unfold, the admin interface still shows the default Django admin. Solution:
  1. Check your settings.py: 
    INSTALLED_APPS = [
    "unfold",  # Must be first!
    "django.contrib.admin",
    # ... other apps
]
  2. Collect static files: 
    python manage.py collectstatic --noinput
  3. Clear browser cache and hard refresh (Ctrl+Shift+R or Cmd+Shift+R)

​
Static Files Not Loading

Problem: Unfold interface appears broken with missing styles or icons. Solution:
1

Collect static files

python manage.py collectstatic --noinput --clear
2

Verify STATIC_URL and STATIC_ROOT

# settings.py
STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'
3

Check web server configuration

Ensure your web server (nginx, Apache, etc.) is correctly serving static files from STATIC_ROOT.

​
Template and Rendering Issues

​
Custom Templates Not Working

Problem: Custom template overrides are not being applied. Solution:
Unfold uses its own template structure. Ensure you’re overriding the correct templates from the unfold/templates/ directory.
  1. Check template directory structure: 
    your_project/
├── templates/
│   └── admin/
│       └── unfold/
│           └── your_custom_template.html
  2. Verify TEMPLATES setting: 
    TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'],  # Include your templates directory
        'APP_DIRS': True,
        # ...
    },
]
Problem: Sidebar navigation is not visible. Solution: Configure sidebar in UNFOLD settings: 
UNFOLD = {
    "SIDEBAR": {
        "show_search": True,
        "navigation": [
            {
                "title": "Navigation",
                "items": [
                    {
                        "title": "Dashboard",
                        "icon": "dashboard",
                        "link": reverse_lazy("admin:index"),
                    },
                ],
            },
        ],
    },
}

​
Form and Widget Issues

​
Select2/Autocomplete Not Working

Problem: Autocomplete fields or Select2 dropdowns are not functioning. Solutions:
Unfold includes jQuery. If your project loads a different jQuery version, conflicts may occur.Fix: Ensure only one jQuery version is loaded, preferably Unfold’s version.
For autocomplete fields:
from unfold.admin import ModelAdmin
from unfold.forms import UnfoldAdminSelectWidget

class MyModelAdmin(ModelAdmin):
    autocomplete_fields = ['related_field']
Open browser DevTools (F12) and check the Console tab for JavaScript errors.

​
File Upload Widget Not Displaying

Problem: File or image upload widgets are not visible or styled incorrectly. Solution: 
from unfold.admin import ModelAdmin
from unfold.widgets import UnfoldAdminFileWidget, UnfoldAdminImageWidget

class MyModelAdmin(ModelAdmin):
    formfield_overrides = {
        models.FileField: {'widget': UnfoldAdminFileWidget},
        models.ImageField: {'widget': UnfoldAdminImageWidget},
    }

​
ArrayField Widget Issues (PostgreSQL)

Problem: ArrayField is not rendering correctly. Solution: Use Unfold’s ArrayWidget: 
from django.contrib.postgres.fields import ArrayField
from unfold.widgets import UnfoldAdminArrayWidget

class MyModelAdmin(ModelAdmin):
    formfield_overrides = {
        ArrayField: {"widget": UnfoldAdminArrayWidget},
    }

​
Inline and Fieldset Issues

​
Inlines Not Showing Tabs

Problem: Inline tabs are not displaying as expected. Solution: Configure tab attribute in your inline class: 
from unfold.admin import TabularInline

class MyInline(TabularInline):
    model = MyModel
    tab = True  # Enable tab display
    # or
    classes = ['tab']  # Alternative method

​
Collapsed Fieldsets Not Working

Problem: Fieldsets with classes = ['collapse'] are not collapsible. Solution: Ensure you’re using Unfold’s fieldset structure: 
class MyModelAdmin(ModelAdmin):
    fieldsets = (
        ('Section Title', {
            'fields': ('field1', 'field2'),
            'classes': ('collapse',),  # Note: tuple, not list
        }),
    )

​
Performance Issues

​
Slow Admin List Views

Problem: Changelist pages load slowly with many records. Solutions:
Always optimize database queries before adjusting pagination settings.
  1. Use select_related and prefetch_related: 
    class MyModelAdmin(ModelAdmin):
    list_select_related = ['foreign_key_field']
    
    def get_queryset(self, request):
        qs = super().get_queryset(request)
        return qs.prefetch_related('many_to_many_field')
  2. Enable infinite pagination: 
    from unfold.paginator import UnfoldInfinitePaginator

class MyModelAdmin(ModelAdmin):
    paginator = UnfoldInfinitePaginator
    show_full_result_count = False
  3. Reduce list_display fields: 
    class MyModelAdmin(ModelAdmin):
    list_display = ['id', 'name', 'status']  # Only essential fields

​
Large Inline Sets

Problem: Change form is slow when there are many inline records. Solution: Use paginated inlines: 
from unfold.admin import TabularInline

class MyInline(TabularInline):
    model = MyModel
    extra = 0
    show_change_link = True
    per_page = 10  # Enable pagination

​
Dark Mode Issues

​
Dark Mode Not Switching

Problem: Dark mode toggle doesn’t work. Solution:
  1. Clear browser local storage
  2. Ensure JavaScript is enabled
  3. Check browser console for errors

​
Custom Styles Not Respecting Dark Mode

Problem: Custom CSS doesn’t adapt to dark mode. Solution: Use Tailwind’s dark mode classes: 
/* Use dark: prefix for dark mode styles */
.my-element {
    @apply bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100;
}

​
Integration Issues

​
django-import-export Not Styled

Problem: Import/Export pages don’t have Unfold styling. Solution: Ensure django-import-export is installed and configured: 
INSTALLED_APPS = [
    "unfold",
    "import_export",  # After unfold
    "django.contrib.admin",
    # ...
]
See the django-import-export integration guide for details.

​
django-simple-history Issues

Problem: History pages not displaying correctly. Solution: Use Unfold’s SimpleHistoryAdmin: 
from unfold.admin import ModelAdmin
from simple_history.admin import SimpleHistoryAdmin

class MyModelAdmin(ModelAdmin, SimpleHistoryAdmin):
    pass

​
Third-Party Package Conflicts

​
Tailwind CSS Conflicts

Problem: Custom Tailwind classes conflicting with Unfold.
Unfold uses Tailwind CSS 4.x. Ensure your custom Tailwind configuration is compatible.
Solution: Use Unfold’s safelist feature: 
UNFOLD = {
    "STYLES": [
        lambda request: static("css/your-custom-styles.css"),
    ],
}

​
Alpine.js Conflicts

Problem: Custom Alpine.js code interfering with Unfold. Solution: Unfold uses Alpine.js v3. Ensure your code is compatible: 
<!-- Use x-data with correct syntax -->
<div x-data="{ open: false }">
    <!-- Your code -->
</div>

​
Production Issues

​
Assets Not Loading in Production

Problem: Static files work in development but not production. Checklist:
  • DEBUG = False in settings
  • STATIC_ROOT is correctly configured
  • python manage.py collectstatic has been run
  • Web server is serving static files from STATIC_ROOT
  • ALLOWED_HOSTS includes your domain
  • Static files have correct permissions (readable by web server)

​
CSRF Token Errors

Problem: Forms failing with CSRF token errors. Solution: 
# settings.py
CSRF_TRUSTED_ORIGINS = [
    'https://yourdomain.com',
    'https://www.yourdomain.com',
]

​
Debugging Tips

​
Enable Django Debug Toolbar

pip install django-debug-toolbar

# settings.py (development only)
if DEBUG:
    INSTALLED_APPS += ['debug_toolbar']
    MIDDLEWARE += ['debug_toolbar.middleware.DebugToolbarMiddleware']
    INTERNAL_IPS = ['127.0.0.1']

​
Check Browser Console

Most JavaScript-related issues appear in the browser console:
  1. Open DevTools (F12)
  2. Go to Console tab
  3. Look for error messages

​
Inspect Network Requests

For static file issues:
  1. Open DevTools Network tab
  2. Refresh the page
  3. Look for failed requests (red status codes)

​
Getting Additional Help

If your issue isn’t covered here:

FAQ

Frequently asked questions

Discord Community

Ask the community for help

GitHub Issues

Search existing issues or create a new one

Professional Support

Get expert assistance

Build docs developers (and LLMs) love

Get started for freeTalk to us