Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/unfoldadmin/django-unfold/llms.txt

Use this file to discover all available pages before exploring further.

Answers to common questions about Django Unfold, its features, and usage.

​
General Questions

Django Unfold is a modern, feature-rich theme for Django Admin that enhances the default admin interface with a beautiful UI, advanced features, and improved workflows. It’s built on top of django.contrib.admin and works alongside the default admin without requiring any migrations.
Yes, Django Unfold is open source and free to use under the MIT License. You can use it in both personal and commercial projects.Professional services like consulting, support, and Studio (advanced features) are available separately for those who need them.
Absolutely! Unfold is designed for incremental adoption. You can:
  • Use it alongside the default Django admin
  • Migrate models one at a time
  • Keep existing customizations while gradually adopting Unfold features
No database migrations or major refactoring required.
Yes! Django Unfold supports:
  • Django 4.2 LTS
  • Django 5.0
  • Django 5.1 (latest)
See the changelog for version-specific details.
  • Django Unfold v0.82.0+: Python 3.11 or higher
  • Earlier versions: Python 3.10+
See the migration guide for upgrade information.

​
Installation and Setup

The most common issue is the order in INSTALLED_APPS. Ensure "unfold" comes before "django.contrib.admin":
INSTALLED_APPS = [
    "unfold",  # Must be first!
    "django.contrib.admin",
    # ... other apps
]
After fixing, run python manage.py collectstatic and clear your browser cache.
No migrations are required! Unfold extends Django’s existing admin without modifying your database schema.However, you should run python manage.py collectstatic to collect Unfold’s static files.
Yes! Django Unfold is production-ready and used by many projects in production environments.Best practices:
  • Always test in a staging environment first
  • Use a specific version (avoid pip install django-unfold without version pinning)
  • Run collectstatic with --clear flag
  • Review the troubleshooting guide for production considerations

​
Features and Functionality

Yes! Unfold offers extensive theming options:
UNFOLD = {
    "COLORS": {
        "primary": {
            "50": "#...",
            "100": "#...",
            # ... other shades
        },
    },
}
See the settings documentation for all customization options.
Yes! Dark mode is built-in and users can toggle between light and dark themes. The preference is saved in local storage.
Yes! Unfold provides tools for creating custom dashboard pages:
from unfold.views import UnfoldView

class CustomDashboardView(UnfoldView):
    template_name = "admin/custom_dashboard.html"
See custom pages documentation for details.
Yes! Unfold includes built-in support for popular packages:
  • django-import-export
  • django-simple-history
  • django-guardian
  • django-constance
  • django-celery-beat
  • django-modeltranslation
  • django-money
  • djangoql
  • And more!
See integrations for configuration guides.
Yes! The command palette (keyboard shortcut: Cmd/Ctrl+K) is available by default. It allows quick navigation across models and custom actions.You can customize it in your UNFOLD settings or disable it with:
UNFOLD = {
    "SHOW_COMMAND_PALETTE": False,
}

​
Customization

Yes! Create templates in your project following Unfold’s structure:
your_project/
├── templates/
│   └── admin/
│       └── unfold/
│           └── custom_template.html
Your templates will override Unfold’s default templates.
Use the STYLES and SCRIPTS settings:
from django.templatetags.static import static

UNFOLD = {
    "STYLES": [
        lambda request: static("css/custom.css"),
    ],
    "SCRIPTS": [
        lambda request: static("js/custom.js"),
    ],
}
See styles and scripts documentation.
Yes! Configure the sidebar in UNFOLD settings:
UNFOLD = {
    "SIDEBAR": {
        "show_search": True,
        "show_all_applications": True,
        "navigation": [
            {
                "title": "My Section",
                "items": [
                    {
                        "title": "Dashboard",
                        "icon": "dashboard",
                        "link": reverse_lazy("admin:index"),
                    },
                ],
            },
        ],
    },
}

​
Performance

Unfold is designed for performance. However, large datasets may require optimization:
  • Use select_related() and prefetch_related() in get_queryset()
  • Enable infinite pagination for large lists
  • Use paginated inlines
  • Optimize list_display fields
See the performance section in troubleshooting.
from unfold.admin import ModelAdmin
from unfold.paginator import UnfoldInfinitePaginator

class MyModelAdmin(ModelAdmin):
    paginator = UnfoldInfinitePaginator
    show_full_result_count = False
    list_select_related = ['foreign_key']
    
    def get_queryset(self, request):
        return super().get_queryset(request).prefetch_related('many_to_many')

​
Troubleshooting

  1. Run python manage.py collectstatic --clear
  2. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
  3. Verify STATIC_URL and STATIC_ROOT settings
  4. Check web server configuration for serving static files
See troubleshooting static files.
Ensure you’re using Unfold’s ModelAdmin:
from unfold.admin import ModelAdmin  # Not django.contrib.admin

@admin.register(MyModel)
class MyModelAdmin(ModelAdmin):  # Not admin.ModelAdmin
    pass
You need to configure sidebar navigation in your settings:
UNFOLD = {
    "SIDEBAR": {
        "navigation": [
            # Your navigation items
        ],
    },
}
Or enable show_all_applications: True to display all registered models.

​
Migration and Compatibility

Yes! This is called “parallel admin” and is useful during migration:
# urls.py
urlpatterns = [
    path('admin/', unfold_admin_site.urls),      # Unfold admin
    path('django-admin/', admin.site.urls),       # Default admin
]
See the parallel admin guide.
Most customizations continue to work, but some may need adjustments:
  • Custom ModelAdmin methods: Usually work without changes
  • Custom templates: May need to use Unfold’s template structure
  • Custom CSS/JS: May need updates for Unfold’s class names
Test thoroughly in a development environment first.
pip install --upgrade django-unfold
python manage.py collectstatic --noinput --clear
Review the migration guide and changelog for breaking changes.

​
Components and UI

Yes! Unfold’s components can be used in custom templates:
{% load unfold %}

{% component "card" title="My Card" %}
    Card content here
{% endcomponent %}
See components documentation.
Use Unfold’s Chart component:
from unfold.components import Chart

Chart(
    chart_type="line",
    data={
        "labels": ["Jan", "Feb", "Mar"],
        "datasets": [{"data": [10, 20, 30]}]
    }
)
See chart documentation.

​
Support and Community

Multiple support channels are available:
Contributions are welcome! You can:
  • Report bugs or suggest features on GitHub
  • Submit pull requests with fixes or features
  • Improve documentation
  • Help others on Discord
See the contributing guide to get started.
Yes! Professional services include:
  • Consulting: Django architecture and Unfold integration
  • Support: Implementation help with 1:1 calls
  • Studio: Advanced features and custom dashboards
Learn more at unfoldadmin.com.

​
Advanced Topics

Yes! Unfold supports all Django admin action types plus custom styling:
from unfold.decorators import action

class MyModelAdmin(ModelAdmin):
    @action(description="Custom Action", url_path="custom")
    def custom_action(self, request, queryset):
        # Your action logic
        pass
See actions documentation.
Unfold supports multiple tab types:
  • Fieldset tabs: Group fieldsets into tabs
  • Inline tabs: Organize inlines in tabs
  • Custom tabs: Create custom tab navigation
See inline tabs, fieldset tabs, and model tabs documentation.
Yes! Show/hide fields based on other field values:
class MyModelAdmin(ModelAdmin):
    conditional_fields = {
        "field_name": {
            "condition": "other_field == 'value'",
            "action": "show",
        },
    }
See conditional fields documentation.

​
Still Have Questions?

If your question isn’t answered here:

Search Documentation

Browse the full documentation

Ask on Discord

Get help from the community

GitHub Discussions

Start a discussion

Professional Support

Get expert assistance

Build docs developers (and LLMs) love

Get started for freeTalk to us