Django Grappelli

Common errors

• ModuleNotFoundError: No module named 'grappelli' or ImportError: No module named grappellidjango.contrib.

  cause The `django-grappelli` package is not installed or not correctly added to `INSTALLED_APPS`.
  fix Run `pip install django-grappelli` to install the package. Then, ensure `'grappelli'` is correctly listed in `INSTALLED_APPS` in your `settings.py`.

• NoReverseMatch at /admin/ Reverse for 'grp_related_lookup' with arguments '()' and keyword arguments '{}' not found.

  cause The `grappelli.urls` are not correctly included in your project's `urls.py`, or are placed after `admin.site.urls`.
  fix In your `urls.py`, ensure `path('grappelli/', include('grappelli.urls'))` is present and placed *before* `path('admin/', admin.site.urls)`.

• Django admin interface is unstyled or partially styled after installing grappelli.

  cause The `grappelli` app is listed after `django.contrib.admin` in `INSTALLED_APPS`, or `collectstatic` was not run.
  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.

• ValueError: invalid literal for int() with base 10: 'some_string' (often related to admin URLs).

  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.
  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()`.

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: In `settings.py`, ensure `'grappelli'` appears before `'django.contrib.admin'`: `INSTALLED_APPS = ('grappelli', 'django.contrib.admin', ...)`
• gotcha 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.
  Fix: In `settings.py`, under `TEMPLATES` -> `'OPTIONS'` -> `'context_processors'`, ensure `django.template.context_processors.request` is present.
• breaking 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.
  Fix: Always use `from django.urls import path, include` and use `path('grappelli/', include('grappelli.urls'))` in your `urls.py`.
• gotcha 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.
  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.

Install

• pip install django-grappelli Install stable version

Imports

• grappelli

  INSTALLED_APPS = ('grappelli', 'django.contrib.admin', ...)

  Grappelli is added to INSTALLED_APPS as a string and must be listed BEFORE 'django.contrib.admin' for correct styling and functionality.
• grappelli.urls
  wrong:

  from django.conf.urls import url, include # for Django 2.0+ projects

  correct:

  from django.urls import path, include
  urlpatterns = [
      path('grappelli/', include('grappelli.urls')), # Grappelli URLS
      path('admin/', admin.site.urls),
  ]

  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`.

Quickstart

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).