pytest-dev/pytest · error · UsageError

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

Error message

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

What it means

Raised by `resolve_collection_argument` (filesystem path mode) when a directory argument also contains `::` selection parts. Selection parts (`::Class::test`) only apply to a Python module file, not to a directory, so pytest rejects selecting inside a bare 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 at the specific file inside the directory: `pytest tests/test_foo.py::TestClass`.
2. Drop the `::` parts to collect the whole directory: `pytest tests/`.
3. Filter with `-k`/`-m` instead of node selection.

Example fix

// before
$ pytest tests/::TestClass
// after
$ pytest tests/test_foo.py::TestClass

from pathlib import Path

def validate_dir_no_selection(arg: str):
    base = arg.split("::", 1)[0]
    if "::" in arg and Path(base).is_dir():
        raise ValueError(f"directory argument cannot contain '::': {arg}")

def selection_target_is_file(arg: str) -> bool:
    from pathlib import Path
    base = arg.split("::", 1)[0]
    p = Path(base)
    return p.is_file() or not p.exists()

When it happens

Trigger: Running `pytest tests/::TestClass` or `pytest tests::test_foo`. The path is a directory and `parts` is non-empty.

Common situations: Assuming `::` works on directories to filter tests inside. Copying a node id that started from a file but trimmed the filename. Shell tab-completion quirks.

Related errors

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

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