# pytest import mechanisms and `sys.path`/`PYTHONPATH`

Here's a list of scenarios where pytest may need to change `sys.path` in order to import test modules or `conftest.py` files.

## Test modules / `conftest.py` files inside packages

Consider this file and directory layout:

    root/
    |- foo/
       |- __init__.py
       |- conftest.py
       |- bar/
          |- __init__.py
          |- tests/
             |- __init__.py
             |- test_foo.py

When executing:

    pytest root/

pytest will find `foo/bar/tests/test_foo.py` and realize it is part of a package given that there's an `__init__.py` file in the same folder. It will then search upwards until it can find the last folder which still contains an `__init__.py` file in order to find the package root (in this case `foo/`). To load the module, it will insert `root/` to the front of `sys.path` (if not there already) in order to load `test_foo.py` as the module `foo.bar.tests.test_foo`.

The same logic applies to the `conftest.py` file: it will be imported as `foo.conftest` module.

Preserving the full package name is important when tests live in a package to avoid problems and allow test modules to have duplicated names. This is also discussed in details in Conventions for Python test discovery.

## Standalone test modules / `conftest.py` files

Consider this file and directory layout:

    root/
    |- foo/
       |- conftest.py
       |- bar/
          |- tests/
             |- test_foo.py

When executing:

    pytest root/

pytest will find `foo/bar/tests/test_foo.py` and realize it is NOT part of a package given that there's no `__init__.py` file in the same folder. It will then add `root/foo/bar/tests` to `sys.path` in order to import `test_foo.py` as the module `test_foo`. The same is done with the `conftest.py` file by adding `root/foo` to `sys.path` to import it as `conftest`.

For this reason this layout cannot have test modules with the same name, as they all will be imported in the global import namespace.

This is also discussed in details in Conventions for Python test discovery.

## Invoking `pytest` versus `python -m pytest`

Running pytest with `python -m pytest [...]` instead of `pytest [...]` yields nearly equivalent behaviour, except that the former call will add the current directory to `sys.path`. See also Calling pytest through python -m pytest.