pytest-dev/pytest · error · UsageError

directory argument cannot contain :: selection parts

Error message

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

What it means

The non-pyargs companion at main.py:1180 raises 'directory argument cannot contain :: selection parts: {arg}' when a plain directory argument (not --pyargs) contains '::'. '::' selects within a file/module; applying it to a directory is meaningless, so pytest rejects it.

Solutions

1. Target a specific file: 'pytest tests/test_x.py::TestClass'.
2. Drop the '::' parts to collect the whole directory.

Example fix

// before
pytest tests/::TestClass
// after
pytest tests/test_x.py::TestClass

from pathlib import Path
def validate_dir_arg(arg: str) -> str:
    base = arg.split('::')[0]
    if '::' in arg and Path(base).is_dir():
        raise ValueError(f'directory {base!r} cannot take :: selection; target a file')
    return arg

When it happens

Trigger: Running 'pytest tests/::TestClass' or 'pytest my_dir::test_func'; passing a directory with '::' selection parts.

Common situations: Confusing directory and file selection semantics; shell autocompletion appending '::'; copy-pasting a nodeid and replacing only the file portion with a directory.

Related errors

• file or directory not found
• not found: (no match in any of )
• package argument cannot contain :: selection parts
• found no collectors for
• Keyword expressions do not support call parameters.

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/656b5b06d365f9c7. 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)