Installation

Install with pip, add the app and its dependencies to your settings, then either run the Vite pipeline for HMR or switch to the pre-built bundle for a Node-free setup.

1. Install the package

pip install adminlte-django

2. Settings

Add the apps and wire the template engine. Because django-components requires an explicit loaders list, you must set APP_DIRS to False and add the AdminLTE context processor:

INSTALLED_APPS = [
    "django_components",
    # ... django.contrib.* ...
    "django_vite",
    "django_adminlte4",
]

MIDDLEWARE = [
    # ...
    "django_components.middleware.ComponentDependencyMiddleware",
]

COMPONENTS = {"dirs": [], "app_dirs": ["components"], "autodiscover": True}

TEMPLATES = [{
    "BACKEND": "django.template.backends.django.DjangoTemplates",
    "DIRS": [],
    # APP_DIRS must be False because we supply an explicit `loaders` list.
    "APP_DIRS": False,
    "OPTIONS": {
        "context_processors": [
            "django.template.context_processors.request",
            "django.contrib.auth.context_processors.auth",
            "django_adminlte4.context_processors.adminlte",
        ],
        "loaders": [(
            "django.template.loaders.cached.Loader",
            [
                "django.template.loaders.filesystem.Loader",
                "django.template.loaders.app_directories.Loader",
                "django_components.template_loader.Loader",
            ],
        )],
        "builtins": ["django_components.templatetags.component_tags"],
    },
}]

STATICFILES_FINDERS = [
    "django.contrib.staticfiles.finders.FileSystemFinder",
    "django.contrib.staticfiles.finders.AppDirectoriesFinder",
    "django_components.finders.ComponentsFileSystemFinder",
]

The app registers Django system checks on startup, so a missing context processor, the wrong APP_DIRS setting, or an unknown ADMINLTE key surfaces on runserver / manage.py check rather than failing silently.

3. Pick an asset mode

AdminLTE serves its front-end one of two ways, controlled by ADMINLTE["assets_mode"]:

Mode	What it does
`"vite"` (default)	Loads assets via `django-vite` — HMR in dev, hashed build in production, optional lazy-loaded plugins.
`"static"`	Serves the compiled bundle shipped inside the package. No Node/npm; `django-vite` is never imported. Just run `collectstatic`.

Node-free (static) setup

Skip the Vite pipeline entirely:

ADMINLTE = {"assets_mode": "static"}

python manage.py collectstatic --noinput

Vite setup

Scaffold the front-end stubs, then install and run Vite. The install command copies assets/app.js, assets/app.scss, assets/adminlte-plugins.js, vite.config.js and a package.json:

python manage.py adminlte_install   # copy the Vite stubs (never overwrites without --force)
npm install                          # admin-lte, bootstrap, overlayscrollbars, bootstrap-icons, sass, vite
npm run dev                          # dev server + HMR (DEBUG=True)
# production: npm run build && python manage.py collectstatic

Then point django-vite at the manifest:

DJANGO_VITE = {
    "default": {
        "dev_mode": DEBUG,
        "manifest_path": BASE_DIR / "assets" / "dist" / "manifest.json",
    }
}

4. URLs & auth (optional)

Wire Django's built-in auth views to get the themed login / logout / password change + reset flow for free:

# urls.py
from django.urls import include, path

urlpatterns = [
    path("", include("django.contrib.auth.urls")),
    # ... your routes ...
]

Next step

Define your dashboard with settings.ADMINLTE — see Configuration.

AdminLTE 4 · Django port Edit on GitHub