pytest-dev/pytest · error · UsageError

package argument cannot contain :: selection parts

Error message

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

What it means

main.py:1180 raises 'package argument cannot contain :: selection parts: {arg}' when --pyargs resolves to a package (directory) AND the argument also contains '::' selection parts. pytest does not support '::Class::method' selection inside a package-level --pyargs argument; you must target a module, not a package, for '::' selection.

Solutions

Point --pyargs at the module inside the package: 'pytest --pyargs mypkg.test_x::SomeTest'.
Drop the '::' parts if you want the whole package collected.

Example fix

// before
pytest --pyargs mypkg::SomeTest  # mypkg is a package
// after
pytest --pyargs mypkg.test_core::SomeTest

Defensive patterns

Strategy: validation

Validate before calling

# If using --pyargs, target a module not a package when adding '::'
import importlib.util
def resolve_pyarg_target(arg: str) -> str:
    mod = arg.split('::')[0]
    spec = importlib.util.find_spec(mod)
    if spec is None:
        raise ValueError(f'{mod!r} not importable')
    if spec.submodule_search_locations is not None and '::' in arg:
        raise ValueError(f'package {mod!r} cannot take :: selection; target a module')
    return arg

Prevention

Point --pyargs at a module (file) when using '::' selection.
Drop '::' to collect a whole package.
Confirm whether the dotted name is a package vs module.

When it happens

Trigger: Running 'pytest --pyargs mypkg::SomeTest' where mypkg is a package directory; mixing a package name with class/method selection under --pyargs.

Common situations: Assuming '::' works the same on packages as on modules under --pyargs; misidentifying a package as a module.

Related errors

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

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