Detect N+1 problems with nplus1 to improve Django performance
Hi everyone, I want to introduce an enhanced version of nplusone called nplus1.
The original nplusone has been unmaintained for around 8 years. I used it for a while and although it was helpful in many cases, I ran into false positives that forced me to whitelist a lot of things, and I also wanted nicer trace messages (inspired by django-zeal). So I decided to maintain and improve it.
A few things that are new or fixed compared to the original:
• Python 3.11+, full type hints (mypy strict + pyright strict)
• Django 4.2 to 5.2 support, SQLAlchemy 2.0 support
• No more false positives on nullable foreign keys (they are valid optimizations and now skipped)
• Proper handling of multi-table inheritance and polymorphic models via PK-based cross-model matching
• Skips checks on 4xx/5xx responses by default (configurable)
• Stack trace with registration site included in every detection message, so you know exactly where the offending query was set up
• New batch reporting mode that collects all detections and reports at the end of a request
• A NPLUSONE_ENABLED = False switch for zero overhead in prod
• Celery support out of the box
• Debug mode that logs every signal during a request
I have been using it in my real project and it works really well, even with complex Django patterns like polymorphic models. It catches almost all N+1 issues as well as redundant prefetch_related and select_related calls.
One thing to note: please only use this in your dev or test environment. The package uses middleware and monkey patches the ORM, so it is not meant for production. For production monitoring, tools like Sentry or Datadog are better suited. There is a NPLUSONE_ENABLED flag that makes it a no-op in prod if you want a single config.
I tested it intensively on Django. For SQLAlchemy and Peewee I mostly ported the original logic and the test suite passes, but I have not battle-tested those ORMs in a real project yet, so feedback is welcome.
Repo: https://github.com/huynguyengl99/nplus1
Hope you find it useful.
Disclaimer: I used Claude Code to help with parts of this, but I read every line, tested it against my own project, and have plenty of open source experience, so please do not write it off as AI slop. And again, since it is dev-only, there is no production performance concern.