Basic test configuration

Command line options and configuration file settings

You can get help on command line options and values in INI-style configurations files by using the general help option:

py.test -h   # prints options _and_ config file settings

This will display command line and configuration file settings which were registered by installed plugins.

How test configuration is read from configuration INI-files

pytest searches for the first matching ini-style configuration file in the directories of command line argument and the directories above. It looks for file basenames in this order:


Searching stops when the first [pytest] section is found in any of these files. There is no merging of configuration values from multiple files. Example:

py.test path/to/testdir

will look in the following dirs for a config file:

... # up until root of filesystem

If argument is provided to a pytest run, the current working directory is used to start the search.

How to change command line options defaults

It can be tedious to type the same series of command line options every time you use pytest. For example, if you always want to see detailed info on skipped and xfailed tests, as well as have terser “dot” progress output, you can write it into a configuration file:

# content of pytest.ini
# (or tox.ini or setup.cfg)
addopts = -rsxX -q

Alternatively, you can set a PYTEST_ADDOPTS environment variable to add command line options while the environment is in use:

export PYTEST_ADDOPTS="-rsxX -q"

From now on, running pytest will add the specified options.

Builtin configuration file options


Specifies a minimal pytest version required for running tests.

minversion = 2.1 # will fail if we run with pytest-2.0

Add the specified OPTS to the set of command line arguments as if they had been specified by the user. Example: if you have this ini file content:

addopts = --maxfail=2 -rf  # exit after 2 failures, report fail info

issuing py.test actually means:

py.test --maxfail=2 -rf

Default is to add no options.


Set the directory basename patterns to avoid when recursing for test discovery. The individual (fnmatch-style) patterns are applied to the basename of a directory to decide if to recurse into it. Pattern matching characters:

*       matches everything
?       matches any single character
[seq]   matches any character in seq
[!seq]  matches any char not in seq

Default patterns are '.*', 'CVS', '_darcs', '{arch}', '*.egg'. Setting a norecursedirs replaces the default. Here is an example of how to avoid certain directories:

# content of setup.cfg
norecursedirs = .svn _build tmp*

This would tell pytest to not look into typical subversion or sphinx-build directories or into any tmp prefixed directory.


One or more Glob-style file patterns determining which python files are considered as test modules.


One or more name prefixes or glob-style patterns determining which classes are considered for test collection. Here is an example of how to collect tests from classes that end in Suite:

# content of pytest.ini
python_classes = *Suite

Note that unittest.TestCase derived classes are always collected regardless of this option, as unittest‘s own collection framework is used to collect those tests.


One or more name prefixes or glob-patterns determining which test functions and methods are considered tests. Here is an example of how to collect test functions and methods that end in _test:

# content of pytest.ini
python_functions = *_test

Note that this has no effect on methods that live on a unittest .TestCase derived class, as unittest‘s own collection framework is used to collect those tests.

See Changing naming conventions for more detailed examples.


One or more doctest flag names from the standard doctest module. See how py.test handles doctests.