# pytest import file mismatch

Classification: dependency
Frameworks: pytest, CI
Canonical: https://automationtester.in/failures/pytest-import-file-mismatch

## Recognizable error

```text
import file mismatch:
imported module 'test_login' has this __file__ attribute:
```

## What it means

pytest imported one test file under a bare module name, then found a second file that would import under the same name. In the default import mode a module name can only belong to one file, so collection stops.

## Minimal repro

Run on 2026-10-23 with pytest 9.1.1, Python 3.11.14, macOS, arm64.

tests/api/test_login.py:

```python
def test_login():
    assert True
```

tests/ui/test_login.py:

```python
def test_login():
    assert True
```

command:

```shell
python -m pytest -q
```

output:

```text
# <project> is the run's working directory, shortened here
___________________ ERROR collecting tests/ui/test_login.py ____________________
import file mismatch:
imported module 'test_login' has this __file__ attribute:
  <project>/tests/api/test_login.py
which is not the same as the test file we want to collect:
  <project>/tests/ui/test_login.py
HINT: remove __pycache__ / .pyc files and/or use a unique basename for your test file modules
=========================== short test summary info ============================
ERROR tests/ui/test_login.py
!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!
1 error in 0.36s
```

## Ranked causes, checks, and fixes

### 1. Two test files share a basename in directories that are not packages

In the default prepend mode, a test file outside a package is imported by its basename, so tests/api/test_login.py and tests/ui/test_login.py both want to be the module test_login. pytest's documentation says each such file needs a unique name.

Diagnostic: The two paths in the message are the two files. If they have the same basename, this is the cause.

Fix: Rename one, add an __init__.py to each directory that holds a colliding file, or switch to `--import-mode=importlib`.

### 2. __init__.py was added, but not where the collision is

The package fix only works when the directories containing the colliding files are packages. In the repro, a tests/__init__.py on its own still failed; __init__.py in tests/api and tests/ui passed.

Diagnostic: Check for __init__.py in the parent directory of each path in the message, not just at the top of the test tree.

Fix: Put __init__.py in every directory between the colliding files and the package root, or use importlib mode instead.

### 3. A second copy of the tests is inside the rootdir

A review checkout, an unpacked artifact or a vendored copy under the repository is collected along with the real tests, and every basename collides. build and dist are skipped by the default norecursedirs, which is why a setuptools build tree rarely causes it, but a directory such as review-copy/ is not.

Diagnostic: If one path in the message is outside your real test directory, a copied tree is being collected.

Fix: Set `testpaths = tests` (or add the copy to `norecursedirs`). In the repro, `-o testpaths=tests` collected 1 passed with the copy still present.

## Verified fix

Make the module names unique: either packages or importlib mode.

pytest.ini (option A):

```ini
[pytest]
addopts = --import-mode=importlib
```

option B:

```shell
touch tests/api/__init__.py tests/ui/__init__.py
```

Evidence: Re-run on 2026-10-23 in a fresh Python 3.11.14 venv with pytest 9.1.1: the pytest.ini above gave 2 passed, and so did the two __init__.py files with no tests/__init__.py beside them. A tests/__init__.py on its own still stopped at 1 error. importlib mode has a cost the docs spell out: test modules can no longer import each other, so shared helpers have to move next to the application code or into conftest.py fixtures.

## When this is not the cause

- **Stale bytecode.** The HINT suggests removing __pycache__ and .pyc files. For two files with the same basename that changes nothing: with PYTHONDONTWRITEBYTECODE=1 and the cache provider off, the error came back and a search afterwards found no __pycache__ directory or .pyc file in the tree.
- **A missing module or package.** If the message is ImportError while importing test module with a ModuleNotFoundError below it, the import failed outright. That is a path or dependency problem, not a name collision.
- **Conftest or fixture scope.** Fixtures resolve by name through conftest.py files, not module names, so renaming or moving fixtures does not touch this error.

## Prevention

- Pick an import mode on day one and write it in pytest config, so local and CI runs agree.
- Set testpaths so the collector never walks into copies, worktrees or artifacts.
- Prefer test file names that say what they cover (test_api_login.py), not only where they live.

## Primary references

- [pytest: sys.path and import modes](https://docs.pytest.org/en/stable/explanation/pythonpath.html)
- [pytest: good practices, choosing an import mode](https://docs.pytest.org/en/stable/explanation/goodpractices.html)
- [pytest source: _pytest/python.py, the import file mismatch message](https://github.com/pytest-dev/pytest/blob/main/src/_pytest/python.py)

Triage this failure locally: https://automationtester.in/tools/test-failure-triage