{"id":7171,"library":"django-grappelli","title":"Django Grappelli","description":"Django Grappelli is a grid-based alternative/extension, essentially a 'jazzy skin,' for the Django administration interface. It aims to improve the usability and aesthetics of the standard Django admin. The current stable version is 4.0.3, which is compatible with Django 5.x. Grappelli's release cycle is closely tied to Django's major versions, ensuring compatibility with the latest stable Django releases.","status":"active","version":"4.0.3","language":"en","source_language":"en","source_url":"https://github.com/sehmaschine/django-grappelli","tags":["django","admin","ui","skin","frontend"],"install":[{"cmd":"pip install django-grappelli","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Grappelli is a skin for the Django Admin. Version 4.0.x requires Django 5.0+, and older Grappelli versions require specific Django releases.","package":"Django"}],"imports":[{"note":"Grappelli is added to INSTALLED_APPS as a string and must be listed BEFORE 'django.contrib.admin' for correct styling and functionality.","symbol":"grappelli","correct":"INSTALLED_APPS = ('grappelli', 'django.contrib.admin', ...)"},{"note":"For Django 2.0+ (and thus Grappelli 4.x), `path` and `include` are from `django.urls`. The `grappelli.urls` must be included before `admin.site.urls`.","wrong":"from django.conf.urls import url, include # for Django 2.0+ projects","symbol":"grappelli.urls","correct":"from django.urls import path, include\nurlpatterns = [\n    path('grappelli/', include('grappelli.urls')), # Grappelli URLS\n    path('admin/', admin.site.urls),\n]"}],"quickstart":{"code":"import os\nfrom pathlib import Path\n\n# Assuming a standard Django project setup for settings.py and urls.py\n# --- settings.py ---\n\nBASE_DIR = Path(__file__).resolve().parent.parent\n\nINSTALLED_APPS = [\n    'grappelli',  # Grappelli must be before django.contrib.admin\n    'django.contrib.admin',\n    'django.contrib.auth',\n    'django.contrib.contenttypes',\n    'django.contrib.sessions',\n    'django.contrib.messages',\n    'django.contrib.staticfiles',\n    # ... other apps\n]\n\nMIDDLEWARE = [\n    'django.middleware.security.SecurityMiddleware',\n    'django.contrib.sessions.middleware.SessionMiddleware',\n    'django.middleware.common.CommonMiddleware',\n    'django.middleware.csrf.CsrfViewMiddleware',\n    'django.contrib.auth.middleware.AuthenticationMiddleware',\n    'django.contrib.messages.middleware.MessageMiddleware',\n    'django.middleware.clickjacking.XFrameOptionsMiddleware',\n]\n\nTEMPLATES = [\n    {\n        'BACKEND': 'django.template.backends.django.DjangoTemplates',\n        'DIRS': [],\n        'APP_DIRS': True,\n        'OPTIONS': {\n            'context_processors': [\n                'django.template.context_processors.debug',\n                'django.template.context_processors.request', # Required for Grappelli Dashboard/Switch User\n                'django.contrib.auth.context_processors.auth',\n                'django.contrib.messages.context_processors.messages',\n            ],\n        },\n    },\n]\n\nSTATIC_URL = '/static/'\nSTATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')\n\n# --- urls.py ---\n\nfrom django.contrib import admin\nfrom django.urls import path, include\n\nurlpatterns = [\n    path('grappelli/', include('grappelli.urls')), # grappelli URLS\n    path('admin/', admin.site.urls), # admin site\n    # ... other url patterns\n]\n\n# After setting up, run:\n# python manage.py collectstatic\n# python manage.py runserver\n# Then visit /admin/ or /grappelli/ (though typically /admin/ is redirected to the grappelli-skinned admin).\n","lang":"python","description":"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."},"warnings":[{"fix":"Always 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.","message":"Grappelli 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.","severity":"breaking","affected_versions":"All major versions (e.g., 2.x, 3.x, 4.x)"},{"fix":"In `settings.py`, ensure `'grappelli'` appears before `'django.contrib.admin'`:\n`INSTALLED_APPS = ('grappelli', 'django.contrib.admin', ...)`","message":"Incorrect 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"In `settings.py`, under `TEMPLATES` -> `'OPTIONS'` -> `'context_processors'`, ensure `django.template.context_processors.request` is present.","message":"Missing `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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `from django.urls import path, include` and use `path('grappelli/', include('grappelli.urls'))` in your `urls.py`.","message":"Django'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.","severity":"breaking","affected_versions":"Django 2.0+ projects upgrading from older configurations, Grappelli versions prior to 3.0"},{"fix":"If `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.","message":"Issues 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.","severity":"gotcha","affected_versions":"All versions with custom user models"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install django-grappelli` to install the package. Then, ensure `'grappelli'` is correctly listed in `INSTALLED_APPS` in your `settings.py`.","cause":"The `django-grappelli` package is not installed or not correctly added to `INSTALLED_APPS`.","error":"ModuleNotFoundError: No module named 'grappelli' or ImportError: No module named grappellidjango.contrib."},{"fix":"In your `urls.py`, ensure `path('grappelli/', include('grappelli.urls'))` is present and placed *before* `path('admin/', admin.site.urls)`.","cause":"The `grappelli.urls` are not correctly included in your project's `urls.py`, or are placed after `admin.site.urls`.","error":"NoReverseMatch at /admin/ Reverse for 'grp_related_lookup' with arguments '()' and keyword arguments '{}' not found."},{"fix":"Move `'grappelli'` to appear *before* `'django.contrib.admin'` in `INSTALLED_APPS` in `settings.py`. Also, ensure you have run `python manage.py collectstatic` to gather Grappelli's static files.","cause":"The `grappelli` app is listed after `django.contrib.admin` in `INSTALLED_APPS`, or `collectstatic` was not run.","error":"Django admin interface is unstyled or partially styled after installing grappelli."},{"fix":"Review your `urls.py` patterns, especially those involving `grappelli.urls` or custom admin views, to ensure regular expressions correctly capture expected numeric values or that all URL parameters are strings. This is less common with modern `path()` syntax but can still happen with `re_path()`.","cause":"This can occur due to an incorrect regular expression in your URLconf, where a URL pattern expects an integer but receives a string with non-digit characters. This is often a misconfiguration of custom admin URLs interacting with Grappelli.","error":"ValueError: invalid literal for int() with base 10: 'some_string' (often related to admin URLs)."}]}