nplusone

Detect the N+1 queries problem in Python ORMs — SQLAlchemy, Peewee, and Django ORM.

A modern rewrite of the original nplusone library, targeting Python 3.11+ with full type annotations, SQLAlchemy 2.0 support, and fixes for false positives found in production Django+DRF codebases.

Installation

pip install nplus1

With optional ORM/framework dependencies:

pip install nplus1[django]           # Django 4.2+
pip install nplus1[sqlalchemy]       # SQLAlchemy 2.0+
pip install nplus1[flask]            # Flask + Flask-SQLAlchemy
pip install nplus1[peewee]           # Peewee 3.15+

Quick Start

Django

Add the middleware to your dev settings:

# settings/dev.py
MIDDLEWARE = [
    ...
    "nplusone.ext.django.NPlusOneMiddleware",
    ...
]

NPLUSONE_ENABLED = True    # set False in prod (zero overhead)
NPLUSONE_LOG = True        # log detections (default)
NPLUSONE_RAISE = True      # raise exceptions in dev/test

Flask + SQLAlchemy

from nplusone.ext.flask_sqlalchemy import NPlusOne

app = Flask(__name__)
NPlusOne(app)

Standalone (any code)

from nplusone.core.profiler import Profiler

with Profiler():
    users = session.query(User).all()
    for user in users:
        user.addresses  # NPlusOneError raised

Celery

from nplusone.ext.celery import NPlusOneCelery

app = Celery("myapp")
NPlusOneCelery(app)

Or manually with signals:

from celery.signals import task_prerun, task_postrun
from nplusone.core.profiler import setup, teardown

@task_prerun.connect()
def on_prerun(**kwargs):
    setup()

@task_postrun.connect()
def on_postrun(**kwargs):
    teardown()

What It Detects

N+1 lazy loads

users = User.objects.all()          # 1 query
for user in users:
    print(user.addresses)           # N queries — flagged!

Fix: use select_related or prefetch_related:

users = User.objects.select_related("addresses").all()

Unnecessary eager loads

users = User.objects.select_related("occupation").all()
for user in users:
    print(user.name)                # occupation never accessed — flagged!

Configuration

All settings work across Django, Flask, and Celery:

Whitelisting

Suppress specific warnings by model, field, or pattern:

NPLUSONE_WHITELIST = [
    {"model": "User", "field": "profile"},       # exact match
    {"model": "myapp.User"},                      # Django app_label.Model format
    {"model": "User*"},                           # fnmatch wildcard
    {"label": "unused_eager_load"},               # suppress all eager load warnings
]

URL Exclusion

Skip detection entirely for URL prefixes where detections are unfixable (e.g. Django admin internals):

NPLUSONE_EXCLUDE_URLS = [
    "/admin/",
    "/debug/",
]

Prod/Dev Split

Only add the middleware in dev/test settings — no need for it in production:

# settings/dev.py (or settings/test.py)
MIDDLEWARE = [
    ...
    "nplusone.ext.django.NPlusOneMiddleware",
    ...
]
NPLUSONE_RAISE = True

No INSTALLED_APPS entry is needed — the ORM patches are applied automatically when the middleware is imported.

For Celery, use NPLUSONE_ENABLED to control whether detection runs:

# settings/base.py
NPLUSONE_ENABLED = False   # Celery setup() is a no-op

# settings/dev.py
NPLUSONE_ENABLED = True    # Celery detection active

Debug Mode

Enable NPLUSONE_DEBUG = True to see every signal fire during a request:

[nplusone.debug] REQUEST START: GET /api/orders/
[nplusone.debug] EAGER_REGISTER: Order.customer (5 instances) at views.py:42 in get_queryset
[nplusone.debug] EAGER_ACCESS: Order.customer (1 instances) at serializers.py:18 in to_representation
[nplusone.debug] DETECTED: Potential unnecessary eager load on Order.shipping_address
[nplusone.debug] REQUEST END: GET /api/orders/ → 200

Detection messages include the registration site (inspired by django-zeal's ZEAL_SHOW_ALL_CALLERS):

Potential unnecessary eager load detected on `Order.shipping_address`
  Registered at: myapp/views.py:42 in get_queryset
                 qs.select_related("customer", "shipping_address")

Comparison

vs. jmcarp/nplusone (original)

This library is a ground-up rewrite of the original nplusone, which has been unmaintained since 2020. We preserve the same detection architecture (blinker signals + ORM monkey-patching) but modernize everything else:

vs. django-zeal

django-zeal is a Django-only N+1 detector with a different approach.

Choose nplusone if you need multi-ORM support, unused eager load detection, or work with complex Django patterns (MTI, polymorphic models, DRF).

Choose django-zeal if you only use Django and want .defer()/.only() detection or configurable thresholds.

Development

# Setup
uv sync

# Run tests
python -m pytest tests/

# Run tests for specific ORM
tox -e py311-django52
tox -e py311-sqlalchemy
tox -e py311-peewee
tox -e py311-flask

# Lint and type check
ruff check nplusone/ tests/
python -m mypy nplusone/
npx pyright

# Coverage
python -m pytest tests/ --cov=nplusone --cov-report=term-missing

Multi-version Testing

# Full matrix
tox

# Specific Python + Django version
tox -e py312-django51
tox -e py313-django42

Docker (PostgreSQL)

docker compose up -d
cp .env.EXAMPLE .env
python -m pytest tests/testapp/

License

MIT. See LICENSE.