Configuration

pytest allows you to customize its behavior through configuration files. These settings control test discovery, default command-line options, custom markers, plugins, and more. Configuration is typically defined in a pytest.ini file placed at the project root. You may also put pytest settings inside tox.ini if you are using tox (a tool that automates testing across multiple isolated virtual environments).

A sample pytest configuration file looks like this:

# pytest.ini
[pytest]
minversion = 6.0
addopts = -rsxX -l
testpaths = src/api_tests src/unit_tests
norecursedirs = .git venv build dist
python_files = test_*.py
python_classes = Test*
python_functions = test_*
xfail_strict = true
markers =
    slow: marks tests as slow (deselect with -m "not slow")

NOTE

A pytest project can contain many configuration files, but only one pytest.ini (or equivalent config file) is used per test run. Pytest stops searching after it finds the first configuration file (pytest.ini, tox.ini, or setup.cfg) relative to the invocation directory.

Here are the common pytest configuration settings:

Setting	Purpose (What it does)
minversion	Enforces a minimum required version of pytest before running tests, preventing issues caused by older pytest features or behavior.
addopts	Defines default command-line options automatically applied to every pytest run, saving you from repeatedly typing common flags.
testpaths	Tells pytest which directories to scan for tests. Useful if your tests aren’t in the default locations or if you want to speed up collection by limiting search paths.
norecursedirs	Tells pytest which directories to ignore entirely during test discovery (e.g., build/, env/, .venv/, large data folders).
python_files	Defines the filename patterns pytest uses to identify test modules. Defaults include test_*.py or *_test.py.
python_classes	Defines the naming pattern for test classes. By default, pytest treats classes starting with Test as test containers.
python_functions	Defines the naming pattern pytest uses for test functions. By default, it detects functions beginning with test_.
markers	Registers custom markers (e.g., @pytest.mark.slow) to avoid "unknown marker" warnings and to document marker usage.
xfail_strict	Makes xfail strict. If enabled, tests marked xfail that unexpectedly pass will be treated as failures (xpass becomes an error).