# pytest-django Documentation

pytest-django is a plugin for pytest that provides a set of useful tools for testing Django applications and projects.

## Quick Start

    $ pip install pytest-django

Make sure `DJANGO_SETTINGS_MODULE` is defined (see Configuring Django settings) and make your tests discoverable (see My tests are not being found. Why?):

### Example using pytest.ini or tox.ini

    # -- FILE: pytest.ini (or tox.ini)
    [pytest]
    DJANGO_SETTINGS_MODULE = test.settings
    # -- recommended but optional:
    python_files = tests.py test_*.py *_tests.py

### Example using pyproject.toml

    # -- Example FILE: pyproject.toml
    [tool.pytest.ini_options]
    DJANGO_SETTINGS_MODULE = "test.settings"
    # -- recommended but optional:
    python_files = ["test_*.py", "*_test.py", "testing/python/*.py"]

Run your tests with `pytest`:

    $ pytest

## Why would I use this instead of Django’s manage.py test command?

Running the test suite with pytest offers some features that are not present in Django’s standard test mechanism:

- Less boilerplate: no need to import unittest, create a subclass with methods. Just write tests as regular functions.

- Manage test dependencies with fixtures.

- Run tests in multiple processes for increased speed.

- There are a lot of other nice plugins available for pytest.

- Easy switching: Existing unittest-style tests will still work without any modifications.

See the pytest documentation for more information on pytest.

## Bugs? Feature Suggestions?

Report issues and feature requests at the GitHub issue tracker.

## Table of Contents

- Getting started with pytest and pytest-django
  - Introduction
  - Talks, articles and blog posts
  - Step 1: Installation
  - Step 2: Point pytest to your Django settings
  - Step 3: Run your test suite
  - Next steps
  - Stuck? Need help?
- Configuring Django settings
  - The environment variable `DJANGO_SETTINGS_MODULE`
  - Command line option `--ds=SETTINGS`
  - `pytest.ini` settings
  - `pyproject.toml` settings
  - Order of choosing settings
  - Using django-configurations
  - Using `django.conf.settings.configure()`
  - Overriding individual settings
  - Changing your app before Django gets set up
- Managing the Python path
  - Automatic looking for Django projects
  - Managing the Python path explicitly
    - Managing your project with virtualenv, pip and editable mode
    - Using pytest’s `pythonpath` option
- Usage and invocations
  - Basic usage
  - Additional command line options
    - `--fail-on-template-vars` - fail for invalid variables in templates
  - Additional pytest.ini settings
    - `django_debug_mode` - change how DEBUG is set
  - Running tests in parallel with pytest-xdist
- Database access
  - Enabling database access in tests
  - Testing transactions
  - Tests requiring multiple databases
  - `--reuse-db` - reuse the testing database between test runs
  - `--create-db` - force re creation of the test database
  - Example work flow with `--reuse-db` and `--create-db`.
  - `--no-migrations` - Disable Django migrations
  - Advanced database configuration
    - Fixtures
    - Examples
- Django helpers
  - Assertions
  - Markers
    - `pytest.mark.django_db` - request database access
    - `pytest.mark.urls` - override the urlconf
    - `pytest.mark.ignore_template_errors` - ignore invalid template variables
  - Fixtures
    - `rf` - `RequestFactory`
    - `async_rf` - `AsyncRequestFactory`
    - `client` - `django.test.Client`
    - `async_client` - `django.test.AsyncClient`
    - `admin_client` - `django.test.Client` logged in as admin
    - `admin_user` - an admin user (superuser)
    - `django_user_model`
    - `django_username_field`
    - `db`
    - `transactional_db`
    - `django_db_reset_sequences`
    - `django_db_serialized_rollback`
    - `live_server`
    - `settings`
    - `django_assert_num_queries`
    - `django_assert_max_num_queries`
    - `django_capture_on_commit_callbacks`
    - `mailoutbox`
  - Automatic cleanup
    - Clearing of site cache
    - Clearing of mail.outbox
- FAQ
  - I see an error saying “could not import myproject.settings”
  - Are Django test tags supported?
  - How can I make sure that all my tests run with a specific locale?
  - My tests are not being found. Why?
  - Does pytest-django work with the pytest-xdist plugin?
  - How can I use `manage.py test` with pytest-django?
  - How can I give database access to all my tests without the django_db marker?
  - How/where can I get help with pytest/pytest-django?
- Contributing to pytest-django
  - Community
  - In a nutshell
  - Contributing Code
    - Getting the source code
    - Syntax and conventions
    - Process
    - Tests
  - Contributing Documentation
- Changelog
  - v4.11.1 (2025-04-03)
    - Bugfixes
  - v4.11.0 (2025-04-01)
    - Compatibility
    - Bugfixes
  - v4.10.0 (2025-02-10)
    - Compatibility
    - Improvements
    - Bugfixes
  - v4.9.0 (2024-09-02)
    - Compatibility
    - Improvements
    - Bugfixes
  - v4.8.0 (2024-01-30)
    - Improvements
    - Bugfixes
  - v4.7.0 (2023-11-08)
    - Compatibility
    - Improvements
  - v4.6.0 (2023-10-30)
    - Compatibility
    - Improvements
    - Bugfixes
  - v4.5.2 (2021-12-07)
    - Bugfixes
  - v4.5.1 (2021-12-02)
    - Bugfixes
  - v4.5.0 (2021-12-01)
    - Improvements
    - Bugfixes
  - v4.4.0 (2021-06-06)
    - Improvements
  - v4.3.0 (2021-05-15)
    - Improvements
  - v4.2.0 (2021-04-10)
    - Improvements
    - Bugfixes
  - v4.1.0 (2020-10-22)
    - Improvements
    - Bugfixes
  - v4.0.0 (2020-10-16)
    - Compatibility
    - Improvements
    - Bugfixes
    - Misc
  - v3.10.0 (2020-08-25)
    - Improvements
    - Misc
  - v3.9.0 (2020-03-31)
    - Improvements
    - Bugfixes
    - Misc
  - v3.8.0 (2020-01-14)
    - Improvements
  - v3.7.0 (2019-11-09)
    - Bugfixes
  - v3.6.0 (2019-10-17)
    - Features
    - Bugfixes
    - Misc
  - v3.5.1 (2019-06-29)
    - Bugfixes
  - v3.5.0 (2019-06-03)
    - Features
    - Bugfixes
    - Misc
  - v3.4.8 (2019-02-26)
    - Bugfixes
  - v3.4.7 (2019-02-03)
    - Bugfixes
  - v3.4.6 (2019-02-01)
    - Bugfixes
    - Misc
  - v3.4.5 (2019-01-07)
    - Bugfixes
    - Misc
  - v3.4.4 (2018-11-13)
    - Bugfixes
    - Features
    - Docs
    - Misc
  - v3.4.3 (2018-09-16)
    - Bugfixes
  - v3.4.2 (2018-08-20)
    - Bugfixes
  - v3.4.0 (2018-08-16)
    - Features
    - Bugfixes
    - Compatibility
  - v3.3.3 (2018-07-26)
    - Bug fixes
    - Docs
  - v3.3.2 (2018-06-21)
    - Bug fixes
    - Compatibility
  - v3.3.0 (2018-06-15)
    - Features
    - Bug fixes
    - Compatibility
  - v3.2.1
  - v3.2.0
    - Features
    - Bug fixes
    - Compatibility
  - v3.1.2
    - Bug fixes
  - v3.1.1
    - Bug fixes
  - v3.1.0
    - Features
    - Compatibility
  - v3.0.0
    - Bug fixes
    - Features
    - Compatibility
  - v2.9.1
    - Bug fixes
  - v2.9.0
    - Features
    - Bug fixes
    - Compatibility
  - v2.8.0
    - Features
    - Bug fixes
  - v2.7.0
    - Features
    - Bugfixes
  - v2.6.2
  - v2.6.1
  - v2.6.0
  - v2.5.1
  - v2.5.0
  - v2.4.0
  - v2.3.1
  - v2.3.0
  - v2.2.1
  - v2.2.0
  - v2.1.0
  - v2.0.1
  - v2.0.0
  - v1.4
  - v1.3
  - v1.2.2
  - v1.2.1
  - v1.2
  - v1.1.1
  - v1.1

## Indices and Tables

- Index

- Module Index