Install & Compatibility
Where this runs
tested against v5.0.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.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 25.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.000s · 26MB
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VERSION
✓ from grappelli import VERSION
✗ import grappelli
To integrate Grappelli into your Django project, first install it via pip. Then, modify your `settings.py` to add 'grappelli' to `INSTALLED_APPS` *before* `django.contrib.admin`. Ensure `django.template.context_processors.request` is enabled in your TEMPLATES options. In your `urls.py`, include `grappelli.urls` using `django.urls.path` and `include`, again *before* `admin.site.urls`. Finally, collect static files to apply the new admin theme.
import os
from pathlib import Path
# Assuming a standard Django project setup for settings.py and urls.py
# --- settings.py ---
BASE_DIR = Path(__file__).resolve().parent.parent
INSTALLED_APPS = [
'grappelli', # Grappelli must be before django.contrib.admin
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
# ... other apps
]
MIDDLEWARE = [
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware',
]
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [],
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request', # Required for Grappelli Dashboard/Switch User
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
]
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
# --- urls.py ---
from django.contrib import admin
from django.urls import path, include
urlpatterns = [
path('grappelli/', include('grappelli.urls')), # grappelli URLS
path('admin/', admin.site.urls), # admin site
# ... other url patterns
]
# After setting up, run:
# python manage.py collectstatic
# python manage.py runserver
# Then visit /admin/ or /grappelli/ (though typically /admin/ is redirected to the grappelli-skinned admin).
Debug
Known issues
breakingGrappelli versions are tightly coupled with Django versions. Grappelli 4.x explicitly requires Django 5.x. Upgrading Django without also upgrading Grappelli (or vice-versa) can lead to broken admin interfaces and runtime errors.fixAlways check the `Versions and Compatibility` section in the official Grappelli documentation for your specific Grappelli and Django versions. Upgrade both packages in tandem or use compatible versions.
affects: All major versions (e.g., 2.x, 3.x, 4.x)
gotchaIncorrect order of 'grappelli' in INSTALLED_APPS. Grappelli must always be listed BEFORE 'django.contrib.admin' for its templates and static files to override the default Django admin correctly. Failing to do so results in an unstyled or partially styled admin interface, or missing functionality.fixIn `settings.py`, ensure `'grappelli'` appears before `'django.contrib.admin'`:
`INSTALLED_APPS = ('grappelli', 'django.contrib.admin', ...)` affects: All versions
gotchaMissing `django.template.context_processors.request`. The Grappelli Dashboard and Switch User features rely on this context processor being enabled in your `TEMPLATES` settings. Without it, these features will not function correctly and may raise errors.fixIn `settings.py`, under `TEMPLATES` -> `'OPTIONS'` -> `'context_processors'`, ensure `django.template.context_processors.request` is present.
affects: All versions
breakingDjango's URL pattern syntax changed from `url()` (regex-based) to `path()` (simpler) starting with Django 2.0. Older Grappelli configurations or tutorials might use `url()` from `django.conf.urls`, which is deprecated and removed in newer Django versions.fixAlways use `from django.urls import path, include` and use `path('grappelli/', include('grappelli.urls'))` in your `urls.py`. affects: Django 2.0+ projects upgrading from older configurations, Grappelli versions prior to 3.0
gotchaIssues with custom user models and the 'Switch User' feature. If you are using a custom user model where `is_superuser` or `is_staff` are defined as properties rather than fields, the 'Switch User' feature might break.fixIf `is_superuser` or `is_staff` are properties, you may need to set `GRAPPELLI_SWITCH_USER_ORIGINAL` and `GRAPPELLI_SWITCH_USER_TARGET` to functions that correctly resolve these attributes. Consult the Grappelli documentation on customization for details.
affects: All versions with custom user models
Upgrade
Version history
5.0.0latest on PyPI · released Apr 29, 2026
Audit
Dependencies
DjangorequiredGrappelli is a skin for the Django Admin. Version 4.0.x requires Django 5.0+, and older Grappelli versions require specific Django releases.