Skip to content

Django N+1

Beta

This package is under active development and the API can change before 1.0.

N+1 query detection for Django.

Based on nplusone by Joshua Carp, a well-established library for automatic N+1 detection across Python ORMs. If you need broad ORM support (SQLAlchemy, Peewee, etc.), nplusone is still the best choice.

Several features (deferred field detection, call-site tracking, .get()-in-a-loop detection, ContextVar-based async safety, and configurable thresholds) were inspired by django-zeal by Tao Bojlen.

django-nplus1 is a Django-only fork that drops legacy compatibility in favour of Python 3.14+ / Django 6+, uses a ContextVar-based signal system, and adds unused eager-load detection.

Features

Detects:

  • Lazy loads on bulk-fetched rows (N+1)
  • Deferred-field access from .defer() / .only()
  • Model.objects.get() repeated in a loop
  • Unused select_related / prefetch_related
  • Duplicate SQL queries, including raw SQL (opt-in via NPLUS1_DETECT_DUPLICATE_QUERIES)
  • Eager loads and fields that no test in the session reads (opt-in corpus mode)

Activates via:

  • Middleware (sync and async)
  • pytest plugin (nplus1 fixture and @pytest.mark.nplus1 marker)
  • Celery task_prerun/task_postrun signals
  • Profiler context manager
  • DetectionContext for other entry points

Suppression:

  • Wildcard whitelist with typo detection
  • # nplus1: ignore inline comments
  • nplus1_allow() context manager
  • # nplus1: corpus-ignore inline comments for corpus mode

Reports via logging, exceptions, warnings.warn_explicit(), and a Django signal. Messages include file, line, and function. Threshold tunable via NPLUS1_THRESHOLD. Only depends on Django.

Quick Start

pip install django-nplus1

# settings.py
INSTALLED_APPS = [
    ...,
    "django_nplus1",
]

# settings/testing.py
MIDDLEWARE = [
    ...,
    "django_nplus1.NPlus1Middleware",
]
NPLUS1_RAISE = True

Adding the middleware to your test settings means every view test that goes through the Django test client will fail on N+1 queries. This catches real problems in actual request paths without false positives from helper functions or scripts that intentionally defer prefetching.

For existing projects, this will likely surface many issues at once. Whitelist them and fix over time; see Whitelisting.

The middleware can also run in development or production settings to log warnings. Other options include the pytest plugin for per-test control and the Profiler context manager for scripts and manual use.

Requirements

  • Python 3.14+
  • Django 6+