{"id":23612,"library":"django-zeal","title":"django-zeal","description":"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.","status":"maintenance","version":"2.1.0","language":"python","source_language":"en","source_url":"https://github.com/taverentech/django-zeal","tags":["django","n-plus-one","query-detection","orm","performance"],"install":[{"cmd":"pip install django-zeal","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required - monkey-patches Django ORM","package":"Django","optional":false}],"imports":[{"note":"Import the single module 'zeal' to activate. No class/function import needed.","symbol":"zeal","correct":"import zeal"}],"quickstart":{"code":"import zeal  # must be imported before any model usage\nfrom myapp.models import Author\n# Example: triggers N+1 warning\nfor author in Author.objects.all():\n    print(author.books.count())\n","lang":"python","description":"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."},"warnings":[{"fix":"Replace 'from zeal import Zeal' or similar with 'import zeal'.","message":"In v2.0.0, the import path changed from 'from zeal import' to just 'import zeal'. Old imports will raise ImportError.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your queries use Django ORM (e.g., related_name, prefetch_related).","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use environment variable ZEAL_VERBOSE instead of zeal.settings.VERBOSE.","message":"The undocumented 'zeal.settings' configuration module is deprecated and will be removed in next major release.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Add 'import zeal' at the very top of manage.py or wsgi.py, before any project imports.","message":"Importing zeal after Django model classes are already defined may not catch all N+1s. It must be imported before any model import.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Replace 'from zeal import Zeal' with 'import zeal'.","cause":"Old import pattern from v1.x used 'from zeal import Zeal'. v2.0.0 renamed the import to just 'import zeal'.","error":"ImportError: cannot import name 'Zeal' from 'zeal'"},{"fix":"Move 'import zeal' to the very beginning of your startup code, before importing any Django apps.","cause":"zeal was imported after some model classes were already loaded, so it failed to patch those models.","error":"RuntimeWarning: No N+1 detector active; did you import zeal before any models?"},{"fix":"Ensure you run 'python manage.py migrate' before starting the server. Import zeal after migrations are applied (or wrap with AppConfig.ready()).","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.","error":"django.db.utils.DatabaseError: no such table: ..."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}