pytest-dev/pytest · error · UsageError

package argument cannot contain :: selection parts: {arg}

Error message

package argument cannot contain :: selection parts: {arg}

What it means

Raised by `resolve_collection_argument` (with `as_pypath=True`) when a `--pyargs` package argument also contains `::` selection parts. pytest does not support selecting a class/function inside a package via dotted-path arguments; selection parts require a concrete module file, not a package directory.

Source

Thrown at src/_pytest/main.py:1180

        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
) -> bool:
    """Check if `arg` is subsumed (contained) by `by`."""
    # First check path subsumption.
    if by.path != arg.path:
        # `by` subsumes `arg` if `by` is a parent directory of `arg` and has no
        # parts (collects everything in that directory).
        if not by.parts:

View on GitHub (pinned to 98b357f69e)

Solutions

1. Point `--pyargs` at the module containing the test: `pytest --pyargs mypkg.tests.test_foo::TestClass`.
2. Drop `--pyargs` and use a filesystem path with `::` selection.
3. Select by keyword (`-k`) or marker (`-m`) instead of node id.

Example fix

// before
$ pytest --pyargs mypkg.tests::TestClass
// after
$ pytest --pyargs mypkg.tests.test_foo::TestClass

def validate_pyargs(arg: str):
    if "::" in arg:
        mod_part = arg.split("::", 1)[0]
        import importlib.util
        spec = importlib.util.find_spec(mod_part)
        if spec is not None and spec.submodule_search_locations is not None:
            raise ValueError(f"package argument cannot contain '::': {arg}")

def pyargs_arg_is_module(arg: str) -> bool:
    import importlib.util
    mod = arg.split("::", 1)[0]
    spec = importlib.util.find_spec(mod)
    return spec is not None and spec.submodule_search_locations is None

When it happens

Trigger: Running `pytest --pyargs mypkg.tests::TestClass` or `--pyargs mypkg::test_foo`. The path resolves to a directory (package) but `parts` is non-empty.

Common situations: Mixing the `--pyargs` dotted syntax with the `::` node-selection syntax. Trying to select within a package as if it were a module.

Related errors

• path cannot contain [] parametrization: {arg}
• module or package not found: {arg} (missing __init__.py?)
• file or directory not found: {arg}
• directory argument cannot contain :: selection parts: {arg}
• Keyword expressions do not support call parameters.

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