pytest-dev/pytest · error · UsageError

module or package not found: {arg} (missing __init__.py?)

Error message

module or package not found: {arg} (missing __init__.py?)

What it means

Raised by `resolve_collection_argument` (with `as_pypath=True`) when a `--pyargs`/import-path style argument cannot be resolved to an importable module or package on sys.path. pytest searched `search_pypath` and found nothing, so it reports the argument and hints that `__init__.py` may be missing.

Source

Thrown at src/_pytest/main.py:1173

        raise UsageError(f"path cannot contain [] parametrization: {arg}")
    parametrization = f"{squacket}{rest}" if squacket else None
    module_name = None
    if as_pypath:
        pyarg_strpath = search_pypath(
            strpath, consider_namespace_packages=consider_namespace_packages
        )
        if pyarg_strpath is not None:
            module_name = strpath
            strpath = pyarg_strpath
    fspath = invocation_path / strpath
    fspath = absolutepath(fspath)
    if not safe_exists(fspath):
        msg = (
            "module or package not found: {arg} (missing __init__.py?)"
            if as_pypath
            else "file or directory not found: {arg}"
        )
        raise UsageError(msg.format(arg=arg))
    if parts and fspath.is_dir():
        msg = (
            "package argument cannot contain :: selection parts: {arg}"
            if as_pypath
            else "directory argument cannot contain :: selection parts: {arg}"
        )
        raise UsageError(msg.format(arg=arg))
    return CollectionArgument(
        path=fspath,
        parts=parts,
        parametrization=parametrization,
        module_name=module_name,
        original_index=arg_index,
    )


def is_collection_argument_subsumed_by(
    arg: CollectionArgument, by: CollectionArgument

View on GitHub (pinned to 98b357f69e)

Solutions

1. Install/import the package: `pip install -e .` or add its root to PYTHONPATH.
2. Add `__init__.py` to make the directory a proper package (or enable namespace packages via `--import-mode=importlib`).
3. Double-check the dotted path spelling and that the target venv is active.
4. Drop `--pyargs` and pass a filesystem path instead.

Example fix

// before
$ pytest --pyargs mypkg.tests.test_foo   # not importable
// after
$ pip install -e .
$ pytest --pyargs mypkg.tests.test_foo

import importlib.util

def module_importable(dotted: str) -> bool:
    return importlib.util.find_spec(dotted) is not None

def is_importable_module(dotted: str) -> bool:
    import importlib.util
    try:
        return importlib.util.find_spec(dotted) is not None
    except (ModuleNotFoundError, ValueError):
        return False

When it happens

Trigger: Running `pytest --pyargs mypkg.tests.test_foo` when `mypkg` is not installed/importable, or when `mypkg/tests` lacks `__init__.py` (not a package). Also when the virtualenv containing the package is not activated.

Common situations: Forgetting to `pip install -e .` the package. Running from the wrong directory/venv. Namespace packages without `__init__.py` when `consider_namespace_packages` is off. Typo in the dotted module path.

Related errors

• package argument cannot contain :: selection parts: {arg}
• path cannot contain [] parametrization: {arg}
• file or directory not found: {arg}
• directory argument cannot contain :: selection parts: {arg}
• --pdbcls: could not import {value!r}: {exc}

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/143604de69218842.json. Report an issue: GitHub.