django-zeal

2.1.0 verified Fri May 01 auth: no python maintenance

Detect N+1 queries in your Django application. v2.1.0 supports Django 4.2+ and Python >=3.9. Maintenance mode: no new features, bug fixes only. GitHub is archived.

pip install django-zeal

Common errors

error ImportError: cannot import name 'Zeal' from 'zeal' ↓

cause Old import pattern from v1.x used 'from zeal import Zeal'. v2.0.0 renamed the import to just 'import zeal'.

fix

Replace 'from zeal import Zeal' with 'import zeal'.

error RuntimeWarning: No N+1 detector active; did you import zeal before any models? ↓

cause zeal was imported after some model classes were already loaded, so it failed to patch those models.

fix

Move 'import zeal' to the very beginning of your startup code, before importing any Django apps.

error django.db.utils.DatabaseError: no such table: ... ↓

cause If zeal is imported before running migrations, it may try to execute queries on non-existent tables when Django's app registry is not ready.

fix

Ensure you run 'python manage.py migrate' before starting the server. Import zeal after migrations are applied (or wrap with AppConfig.ready()).

Warnings

breaking In v2.0.0, the import path changed from 'from zeal import' to just 'import zeal'. Old imports will raise ImportError. ↓

fix Replace 'from zeal import Zeal' or similar with 'import zeal'.

gotcha django-zeal only works with the Django ORM's internal query mechanics; it does NOT detect N+1s from raw SQL or third-party DB backends. ↓

fix Ensure your queries use Django ORM (e.g., related_name, prefetch_related).

deprecated The undocumented 'zeal.settings' configuration module is deprecated and will be removed in next major release. ↓

fix Use environment variable ZEAL_VERBOSE instead of zeal.settings.VERBOSE.

gotcha Importing zeal after Django model classes are already defined may not catch all N+1s. It must be imported before any model import. ↓

fix Add 'import zeal' at the very top of manage.py or wsgi.py, before any project imports.

Imports

zeal
```
import zeal
```
Import the single module 'zeal' to activate. No class/function import needed.

Quickstart

Simply import zeal at the top of your Django app entry point (e.g., settings.py or manage.py). It will automatically log N+1 queries detected during request/response cycle.

import zeal  # must be imported before any model usage
from myapp.models import Author
# Example: triggers N+1 warning
for author in Author.objects.all():
    print(author.books.count())