pytest-dev/pytest · error · UsageError

module or package not found

Error message

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

What it means

main.py:1173 raises 'module or package not found: {arg} (missing __init__.py?)' when --pyargs (as_pypath=True) is used and the given module path cannot be imported/found on sys.path via search_pypath. The message hints at a missing __init__.py because that is the most common reason a package cannot be imported.

Solutions

1. Install the package editable: 'pip install -e .' so it is importable.
2. Add __init__.py to make the directory a proper package.
3. Confirm 'python -c "import myproj.tests.test_x"' works in the same environment.
4. Check the spelling of the dotted module path.

Example fix

// before
pytest --pyargs myproj.tests.test_x  # not installed
// after
pip install -e . && pytest --pyargs myproj.tests.test_x

# Verify module importability before running with --pyargs
import importlib, sys
def assert_importable(dotted: str):
    try:
        importlib.import_module(dotted)
    except ImportError as e:
        raise SystemExit(f'{dotted!r} not importable: {e}; pip install -e . or add __init__.py')

When it happens

Trigger: Running 'pytest --pyargs myproj.tests.test_x' where myproj is not installed/importable; a package missing __init__.py; running from the wrong virtualenv where the module is absent; namespace package issues.

Common situations: Forgetting to pip install -e . the local package; missing __init__.py in a test package; wrong/activated virtualenv; the module name typo'd.

Related errors

• package argument cannot contain :: selection parts
• Can't find module at location
• cannot delete key in keywords dict
• Could not resolve for
• directory argument cannot contain :: selection parts

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/143604de69218842. Report an issue: GitHub.

Appendix: 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 0d6fbdeffa)