django-nplus1

N+1 query detection for Django. The API is in beta and can still change before 1.0.

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, introducing django-nplus1 will likely surface many N+1 queries at once. Whitelist the known issues and fix them over time:

# settings/testing.py
NPLUS1_WHITELIST = [
    {"model": "myapp.Author", "field": "books"},
    {"model": "myapp.Book", "field": "publisher"},
]

The middleware can also run in development or production settings to log warnings instead of raising. See the docs for all options, including the pytest plugin and the Profiler context manager.

See examples/ for a working project.

Corpus Mode

Per-request unused_eager_load detection can produce false positives on shared prefetch patterns. Corpus mode collects eager loads across the full pytest session and only reports the ones no test read:

uv run pytest --nplus1-eager-corpus

It also reports concrete fields that were loaded but never read across the suite, as unused_field_load. Suppress noisy models with NPLUS1_FIELD_EXCLUDE = ["auth.User", "contenttypes.*"].

See docs for suppression markers and pytest-xdist support.

Celery Integration

The equivalent of the middleware for Celery tasks. Each task execution gets its own detection scope.

pip install "django-nplus1[celery]"

# settings.py (or settings/testing.py)
NPLUS1_CELERY = True

Lazy loads, .get()-in-a-loop and unused eager loads are detected per task, just as they are per request, and so are duplicate queries when NPLUS1_DETECT_DUPLICATE_QUERIES is on. nplus1_allow() works inside tasks the same way it does in views.

Limitations:

• nplus1_allow() context does not propagate across task boundaries. If a view calls task.delay() inside an nplus1_allow() block, the allow rules do not carry into the worker (ContextVars don't survive serialization).
• A detection made when a task ends, such as an unused eager load, or one that the task catches, can't fail the task, because Celery has already recorded its result. It is logged at ERROR level on the django_nplus1 logger instead. For a task run with .apply() inside another scope, such as a request or the nplus1 test fixture, that scope reports the detection when it ends.
• With NPLUS1_RAISE, a detection fails the task, and a task with autoretry_for=(Exception,) is retried for it.

Credits

This project builds on the work of:

• nplusone by Joshua Carp, the original automatic N+1 detection library for Python ORMs. django-nplus1 started as a Django-specific fork of nplusone's architecture.
• django-zeal by Tao Bojlen, which inspired several features: deferred field detection, .get()-in-a-loop detection, ContextVar-based async safety, call-site tracking, and configurable thresholds.

License

MIT