---
id: django-perf-rec
version: "4.31.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# django-perf-rec — Keep detailed records of the performance of your Django code.

License: permissive · Maintenance: active · Downloads: 100.1K/mo

## What it is and what it does

django-perf-rec is a test instrumentation tool that records all database queries and cache operations executed within a test context, storing them in a YAML file for comparison on subsequent runs. When a test runs again, the new operations are compared against the stored record; if they differ, the test fails, alerting you to performance regressions. The tool fingerprints queries and cache keys by replacing variable data (like primary keys) with `#` and truncating long strings with `...`, so that incidental changes like new columns or different random data don't cause spurious test failures.

It wraps Django's lower-level `assertNumQueries` with a much richer view of what actually happened during test execution. You use it as a context manager around the code you want to profile, and it automatically determines the test name and file path for storing records. The package also provides hooks to selectively capture tracebacks for debugging specific operations and to filter which operations get recorded, useful for hiding test-only queries that would be handled differently in production.

Use it for:

- Catch unintended N+1 queries introduced by code changes before they reach production.
- Document expected database and cache behavior for a test as a regression baseline.
- Debug which code paths trigger specific database queries using optional traceback capture.
- Exclude test-only database operations from performance records using operation filters.
- Enforce consistent query patterns across a Django test suite without manual assertion counts.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Records and compares Django database queries and cache operations in tests, detecting performance regressions by storing fingerprinted operation logs in YAML files.

Yes, if you maintain a Django test suite and want to detect performance regressions automatically. The low install friction, permissive license, and active maintenance make it a practical choice. Note that the author recommends inline-snapshot-django as a faster alternative for new projects, so consider whether that better fits your needs; django-perf-rec remains suitable for existing codebases and will continue to receive maintenance.

## Install

pip install django-perf-rec
uv add django-perf-rec
poetry add django-perf-rec

## Installing django-perf-rec

Before you install: Low friction install with three stable runtime dependencies (django, pyyaml, sqlparse). Package is actively maintained and in use, though the author notes it is now in maintenance mode with a newer alternative (inline-snapshot-django) available.

License in practice: MIT license permits commercial and private use with minimal restrictions—suitable for most projects.

Quickstart:

pip install django-perf-rec

import django_perf_rec

with django_perf_rec.record():
    self.client.get("/")

Requires Django 4.2 to 6.0 and Python 3.9 or later; intended for use within Django test cases.

Verify before relying:

- Performance overhead of recording and fingerprinting operations during test runs.
- Compatibility with test runners other than Django's default (pytest support mentioned but not detailed).
- How YAML file diffs are presented and whether they integrate with CI/CD systems.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 100.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

django query performance testing, track database queries in tests, detect django performance regressions, cache operation monitoring django, assertNumQueries alternative, django test performance recording, sql query tracking tests, django-testing, performance-monitoring, regression-detection

[View on SkillFed](https://skillfed.io/packages/django-perf-rec) · [View on PyPI](https://pypi.org/project/django-perf-rec/)