# 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:

    pytest -h   # prints options _and_ config file settings

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

## Initialization: determining rootdir and inifile

pytest determines a `rootdir` for each test run which depends on the command line arguments (specified test files, paths) and on the existence of ini-files. The determined `rootdir` and ini-file are printed as part of the pytest header during startup.

Here's a summary what `pytest` uses `rootdir` for:

- Construct nodeids during collection; each test is assigned a unique nodeid which is rooted at the `rootdir` and takes in account full path, class name, function name and parametrization (if any).
- Is used by plugins as a stable location to store project/test run specific information; for example, the internal cache plugin creates a `.pytest_cache` subdirectory in `rootdir` to store its cross-test run state.

Important to emphasize that `rootdir` is NOT used to modify `sys.path`/`PYTHONPATH` or influence how modules are imported. See pytest import mechanisms and sys.path/PYTHONPATH for more details.

`--rootdir=path` command-line option can be used to force a specific directory. The directory passed may contain environment variables when it is used in conjunction with `addopts` in a `pytest.ini` file.

### Finding the `rootdir`

Here is the algorithm which finds the rootdir from `args`:

- determine the common ancestor directory for the specified `args` that are recognised as paths that exist in the file system. If no such paths are found, the common ancestor directory is set to the current working directory.
- look for `pytest.ini`, `tox.ini` and `setup.cfg` files in the ancestor directory and upwards. If one is matched, it becomes the ini-file and its directory becomes the rootdir.
- if no ini-file was found, look for `setup.py` upwards from the common ancestor directory to determine the `rootdir`.
- if no `setup.py` was found, look for `pytest.ini`, `tox.ini` and `setup.cfg` in each of the specified `args` and upwards. If one is matched, it becomes the ini-file and its directory becomes the rootdir.
- if no ini-file was found, use the already determined common ancestor as root directory. This allows the use of pytest in structures that are not part of a package and don't have any particular ini-file configuration.

If no `args` are given, pytest collects test below the current working directory and also starts determining the rootdir from there.

warning: | custom pytest plugin commandline arguments may include a path, as in `pytest --log-output ../../test.log args`. Then `args` is mandatory, otherwise pytest uses the folder of test.log for rootdir determination (see also issue 1435). A dot `.` for referencing to the current working directory is also possible.

Note that an existing `pytest.ini` file will always be considered a match, whereas `tox.ini` and `setup.cfg` will only match if they contain a `[pytest]` or `[tool:pytest]` section, respectively. Options from multiple ini-files candidates are never merged - the first one wins (`pytest.ini` always wins, even if it does not contain a `[pytest]` section).

The `config` object will subsequently carry these attributes:

- `config.rootdir`: the determined root directory, guaranteed to exist.
- `config.inifile`: the determined ini-file, may be `None`.

The rootdir is used as a reference directory for constructing test addresses ("nodeids") and can be used also by plugins for storing per-testrun information.

Example:

    pytest path/to/testdir path/other/

will determine the common ancestor as `path` and then check for ini-files as follows:

    # first look for pytest.ini files
    path/pytest.ini
    path/setup.cfg  # must also contain [tool:pytest] section to match
    path/tox.ini    # must also contain [pytest] section to match
    pytest.ini
    ... # all the way down to the root

    # now look for setup.py
    path/setup.py
    setup.py
    ... # all the way down to the root

## 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
    # setup.cfg files should use [tool:pytest] section instead
    [pytest]
    addopts = -ra -q

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

    export PYTEST_ADDOPTS="-v"

Here's how the command-line is built in the presence of `addopts` or the environment variable:

    <pytest.ini:addopts> $PYTEST_ADDOPTS <extra command-line arguments>

So if the user executes in the command-line:

    pytest -m slow

The actual command line executed is:

    pytest -ra -q -v -m slow

Note that as usual for other command-line applications, in case of conflicting options the last one wins, so the example above will show verbose output because `-v` overwrites `-q`.

## Builtin configuration file options

For the full list of options consult the reference documentation.