pytest-django: Running Django Tests with pytest

The Django and pytest Testing Gap pytest-django Addresses

pytest-django is intended for developers who already use or want to use Django but prefer pytest as the test runner. Django applications have their own testing facilities and the `manage.py test` command, while pytest supplies features such as fixtures, test discovery, assertions, and a plugin system. The plugin connects those environments so a Django project can execute tests through pytest without discarding Django-specific test setup.

The target audience is broader than teams willing to rewrite every test. The README specifically says existing unittest-style `TestCase` tests continue to work without modification. New tests can be regular Python functions rather than methods belonging to a subclass, which removes structural requirements associated with unittest. Teams can therefore introduce pytest gradually, although the README excerpt does not describe a migration procedure.

This makes pytest-django suitable for application tests, reusable Django test infrastructure, and projects whose developers also want to combine Django with other pytest plugins. It does not replace Django itself and is not a standalone test framework. The package intentionally does not depend on Django, so a Django installation and a supported version must already fit the application's dependency plan.

Plugin Hooks and the Supported Django Test Stack

pytest-django is packaged as a pytest plugin rather than as a standalone command-line application. Its `pyproject.toml` declares the project name `pytest-django`, depends on `pytest>=7.0.0`, and uses `setuptools` as its build backend. The optional `django` dependency group adds `django>=5.2`. This split is deliberate: the package can obtain a compatible lower bound for the project's Django version while leaving the application responsible for selecting Django itself.

The documented compatibility for current releases covers Django 5.2, Django 6.1, and the latest main branch at the time of each release. Supported Python runtimes are CPython 3.10 or later and PyPy 3. The package metadata also lists Python 3.10 through 3.14. Older Django versions are not covered by the current compatibility statement, so an older project would need to select an older pytest-django release.

The README excerpt does not expose the plugin's internal hook implementations. It does establish the integration boundary: pytest supplies collection, fixtures, and its plugin system, while pytest-django provides the compatibility layer needed for Django testing. The repository layout includes the `pytest_django/` package and a separate `pytest_django_test/` suite, indicating that plugin code and its own tests are maintained as distinct trees. The exact hook sequence is not described here and should be checked in the full documentation or source before changing low-level collection behavior.

Installing pytest-django and Reaching a First Test Run

The installation command documented in the README comes from PyPI. The current package requires Python 3.10 or later. Run this command in the same environment used for the Django application:

pip install pytest-django

After installation, pytest should be able to discover the installed plugin when the project runs its test suite. The README does not document a project-specific settings file, a required `pytest.ini` block, or a dedicated pytest-django command for this first run. It directs readers to the online quick start for fuller setup rather than including those details here.

A practical first check is therefore limited to confirming that pytest starts with the plugin available and that a simple Django-oriented test is collected. The README excerpt does not provide a runnable Django test file or database configuration, so supplying either would add settings that are not documented. Projects with existing Django tests can use that suite as the initial check. Existing `TestCase` classes should remain valid according to the README, which makes them a more defensible starting point than inventing project-specific fixtures before configuration has been reviewed.

Fixtures, Database Reuse, and Parallel pytest Runs

The main reason to choose pytest-django over Django's default runner is access to pytest facilities while retaining Django behavior. The README highlights fixture-managed test dependencies, lower test boilerplate, database reuse across a test run, multi-process execution through `pytest-xdist`, and compatibility with other pytest plugins. These benefits are most relevant when a project already has shared setup such as authenticated users, form submissions, model factories, or application-specific state.

Database reuse does not mean that pytest-django removes isolation. According to the README, the advantage is avoiding recreation of the test database for every test run. The excerpt does not state the exact database configuration, cleanup policy, transaction behavior, or limits on parallel access. Those details must be verified in the full documentation or in the project's own database fixtures before assuming that concurrent tests are safe.

Parallel execution is described as a benefit but depends on the separate `pytest-xdist` plugin. pytest-django does not present parallelism as an automatic feature of this package. Projects must install and configure `pytest-xdist`, confirm that test data can be isolated between workers, and check that database-backed tests do not depend on shared mutable records. The README supports the general capability, while it remains silent about worker configuration. A team interested in shorter runs should evaluate parallelism as an integration project rather than as a zero-configuration benefit.

Compatibility Boundaries for Older Django Projects

The current release line has an explicit compatibility target. The README names Django 5.2, Django 6.1, and the latest main branch, with compatibility determined at each pytest-django release. It also requires `pytest>=7.0` and CPython 3.10 or newer. Projects running older Django versions should use previous pytest-django releases rather than assuming that the newest plugin release will accept their dependency range.

This is a meaningful adoption constraint. The optional `django` extra requests `django>=5.2`, and `pyproject.toml` does not advertise support for earlier Django branches. Selecting an older plugin release may also mean accepting the Python and pytest compatibility associated with that release. The README does not provide a historical version matrix, so an upgrade decision requires consulting the changelog and documentation for the candidate version rather than inferring compatibility from the current release.

The package is also not documented as a complete replacement for every part of `manage.py test`. The README supports the claim that existing `TestCase` tests work without modification, but it does not claim that all custom runners, management-command tests, settings arrangements, or test ordering behavior are identical. Teams with specialized Django test infrastructure should compare those pieces before removing the built-in runner.

pytest-django Versus Django's manage.py test

The clearest alternative is Django's `manage.py test` command. It is part of Django and is designed to run Django tests without installing another plugin. A project that uses few shared fixtures, does not need pytest plugins, and has no reason to adopt pytest may gain little from changing runners. The README does not state that every Django project needs pytest-django.

pytest-django changes the surrounding execution model. Tests can be regular functions and can request setup through pytest fixtures. The suite can also use other pytest plugins and, when `pytest-xdist` is present, run in multiple processes. The README also identifies database reuse as an advantage, specifically avoiding recreation of the test database for every test run. Django's built-in runner remains the simpler choice when those pytest features do not justify the compatibility work.

Migration can be incremental because existing unittest-style `TestCase` tests remain compatible. That does not mean pytest and Django have no separate configuration concerns. The plugin must load correctly, pytest must discover the tests, and project-specific Django settings and database fixtures must work in the pytest environment. The README excerpt does not document those settings, so adoption should be based on the full tutorial and changelog rather than the short installation example alone.

Maintenance, Releases, and Upgrade Work

The repository is not archived, and its last push was on 2026-10-05. Recent releases include v4.14.0 on 2026-08-10, v4.13.0 on 2026-08-05, and v4.12.0 on 2026-08-03. These dates show recent release activity, but the README does not provide a long-term support policy or a migration guide for each release. An upgrade should therefore account for changes in the changelog and the Django version boundary.

The current release documentation says that older Django versions require previous pytest-django releases. That creates an explicit maintenance cost for projects that cannot move to Django 5.2 or later: they need to track compatible plugin versions separately from the latest line. Projects on the current compatibility range still need to verify pytest, Python, Django, and plugin versions together because the plugin's dependency metadata is only one part of the environment.

The README labels the license as BSD, while `pyproject.toml` points to the repository's `LICENSE` file through the `license` field. This is a packaging and attribution detail rather than legal advice. Anyone distributing the package or incorporating its code should inspect that file and the repository's contribution documentation for the actual terms. `pyproject.toml` classifies the project as `OSI Approved :: BSD License` and includes `Development Status :: 5 - Production/Stable`.

Editorial conclusion

Adopt pytest-django when a Django project wants pytest fixtures and plugins without rewriting existing unittest-style tests. Do not choose it when `manage.py test` is sufficient or the project cannot move to Python 3.10 or newer. Before adoption, verify compatibility with the required Django version, pytest plugins, database fixtures, and legacy tests, then inspect the repository's LICENSE file for the distribution terms.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. pytest-dev/pytest-django on GitHub
4. README
5. Releases