pytest-dev/pytest · error · UsageError

path cannot contain [] parametrization

Error message

path cannot contain [] parametrization: {arg}

What it means

resolve_collection_argument (main.py:1155) splits the argument on '[' to detect parametrization like 'test_file.py::test_func[a-b]'. If a '[' appears but there are no '::' selection parts beforehand, the brackets cannot attach to any test ID, so pytest raises UsageError('path cannot contain [] parametrization: {arg}'). The brackets are only valid as a suffix to a '::' selection.

Solutions

1. Move the bracket suffix to after a '::' selection: 'path::test_name[param]'.
2. Quote the path argument to prevent shell glob expansion injecting brackets.
3. Rename files/dirs that literally contain '[' or ']' characters.

Example fix

// before
pytest tests[smoke].py
// after
pytest tests/test_smoke.py::test_login[guest]

import re
def validate_arg(arg: str) -> str:
    if '[' in arg and '::' not in arg.split('[')[0]:
        raise ValueError(f'brackets require a :: selection: {arg!r}')
    return arg

When it happens

Trigger: Running 'pytest tests[a-b].py' (brackets on the file path); 'pytest path[1]' with no '::'; misusing glob/shell expansion that injects brackets into a path argument.

Common situations: Shell glob producing bracketed paths; typos placing parametrization before '::'; attempting to parametrize a file path rather than a test.

Related errors

• directory argument cannot contain :: selection parts
• file or directory not found
• found no collectors for
• not found: (no match in any of )
• package argument cannot contain :: selection parts

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

Appendix: source

Thrown at src/_pytest/main.py:1155

        "pkg.tests.test_foo::TestClass::test_foo[a,b]"

    In which case we search sys.path for a matching module, and then return the *path* to the
    found module, which may look like this:

        CollectionArgument(
            path=Path("/home/u/myvenv/lib/site-packages/pkg/tests/test_foo.py"),
            parts=["TestClass", "test_foo"],
            parametrization="[a,b]",
            module_name="pkg.tests.test_foo",
        )

    If the path doesn't exist, raise UsageError.
    If the path is a directory and selection parts are present, raise UsageError.
    """
    base, squacket, rest = arg.partition("[")
    strpath, *parts = base.split("::")
    if squacket and not parts:
        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))

View on GitHub (pinned to 0d6fbdeffa)