Skip to main content

​
Prerequisites

Before installing Django Unfold, ensure your project meets these requirements:

Python Version

Python 3.11 or higher

Django Version

Django 4.2, 5.0, 5.1, 5.2, or 6.0
Django Unfold requires Python 3.11 or newer. If you’re using an older version of Python, you’ll need to upgrade before proceeding.

​
Installation Steps

1

Install the Package

Install Django Unfold using pip:
pip install django-unfold
This will install the latest stable version from PyPI.
2

Update INSTALLED_APPS

Add unfold to your INSTALLED_APPS in settings.py. Important: Place it before django.contrib.admin:
settings.py
INSTALLED_APPS = [
    "unfold",  # Must come before django.contrib.admin
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # Your other apps...
]
The order is critical! Unfold must be listed before django.contrib.admin to properly override the default admin templates.
3

Collect Static Files

Run Django’s collectstatic command to gather Unfold’s static assets:
python manage.py collectstatic
This copies all CSS, JavaScript, and other static files to your STATIC_ROOT directory.
4

Verify Installation

Start your development server and access the admin interface:
python manage.py runserver
Navigate to http://127.0.0.1:8000/admin/ and you should see the new Unfold interface!

​
Optional Dependencies

Django Unfold includes optional integrations for popular Django packages. Install these if you need their functionality:
For enhanced filtering capabilities:
settings.py
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.filters",  # Advanced filter support
    "django.contrib.admin",
    # ...
]
For improved form widgets and styling:
settings.py
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.forms",  # Enhanced form support
    "django.contrib.admin",
    # ...
]
For advanced inline features:
settings.py
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.inlines",  # Advanced inline support
    "django.contrib.admin",
    # ...
]
For django-import-export support:
pip install django-import-export
settings.py
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.import_export",
    "django.contrib.admin",
    # ...
    "import_export",
]
For django-simple-history support:
pip install django-simple-history
settings.py
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.simple_history",
    "django.contrib.admin",
    # ...
    "simple_history",
]
For django-guardian permission support:
pip install django-guardian
settings.py
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.guardian",
    "django.contrib.admin",
    # ...
    "guardian",
]
For django-constance dynamic settings:
pip install django-constance
settings.py
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.constance",
    "django.contrib.admin",
    # ...
    "constance",
]

​
Configuration

​
Basic Configuration

Django Unfold works out of the box with sensible defaults. However, you can customize various aspects through your settings.py:
settings.py
# Unfold settings (all optional)
UNFOLD = {
    "SITE_TITLE": "My Admin Panel",
    "SITE_HEADER": "My Administration",
    "SITE_URL": "/",
    # Add more configuration options as needed
}

​
Static Files Configuration

Ensure your static files are properly configured:
settings.py
STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

# For development
STATICFILES_DIRS = [
    BASE_DIR / "static",
]

​
Media Files Configuration

If you’re using file uploads in your admin:
settings.py
MEDIA_URL = "/media/"
MEDIA_ROOT = BASE_DIR / "media"

​
Running Alongside Default Admin

Django Unfold supports running alongside the default Django admin. This is useful for gradual migration or testing: 
from django.contrib import admin
from django.urls import path
from unfold.sites import UnfoldAdminSite

# Create a separate Unfold admin site
unfold_admin_site = UnfoldAdminSite(name="unfold_admin")

# Register your models with both sites if needed
# unfold_admin_site.register(MyModel, MyModelAdmin)

urlpatterns = [
    path("admin/", admin.site.urls),  # Default admin
    path("unfold-admin/", unfold_admin_site.urls),  # Unfold admin
]
When running both admin interfaces, you can access the default admin at /admin/ and the Unfold admin at /unfold-admin/.

​
Troubleshooting

Solution: Make sure unfold is listed before django.contrib.admin in INSTALLED_APPS and that you’ve run collectstatic.
Solution: Run python manage.py collectstatic and verify your STATIC_URL and STATIC_ROOT settings are correct.
Solution: Ensure you’re importing from the correct modules:
from unfold.admin import ModelAdmin  # Correct
from django.contrib.admin import ModelAdmin  # Wrong
Solution: Check that APP_DIRS is set to True in your TEMPLATES setting:
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,  # Must be True
        # ...
    },
]

​
Next Steps

Now that Django Unfold is installed, you’re ready to start building your admin interface:

Quick Start Guide

Learn how to create your first Unfold admin interface

Full Documentation

Explore all features and configuration options
Installation complete! Continue to the Quick Start guide to build your first admin interface.

Build docs developers (and LLMs) love

Get started for freeTalk to us