pytest-dev/pytest · error · UsageError

{optname} must be a filename, given: {path}

Error message

{optname} must be a filename, given: {path}

What it means

The filename_arg function is an argparse type validator used by pytest CLI options (e.g., --pdbcls, --override-ini file args) that must receive a file path, not a directory. If the provided path resolves to an existing directory, pytest raises UsageError. This prevents pytest from treating a directory where it expects a file.

Source

Thrown at src/_pytest/config/__init__.py:297

    from _pytest.deprecated import CONSOLE_MAIN

    warnings.warn(CONSOLE_MAIN, stacklevel=2)
    return _console_main()


class cmdline:  # compatibility namespace
    main = staticmethod(main)


def filename_arg(path: str, optname: str) -> str:
    """Argparse type validator for filename arguments.

    :path: Path of filename.
    :optname: Name of the option.
    """
    if os.path.isdir(path):
        raise UsageError(f"{optname} must be a filename, given: {path}")
    return path


def directory_arg(path: str, optname: str) -> str:
    """Argparse type validator for directory arguments.

    :path: Path of directory.
    :optname: Name of the option.
    """
    if not os.path.isdir(path):
        raise UsageError(f"{optname} must be a directory, given: {path}")
    return path


# Plugins that cannot be disabled via "-p no:X" currently.
essential_plugins = (
    "mark",
    "main",

View on GitHub (pinned to 98b357f69e)

Solutions

1. Point the option at a specific file (e.g., myplugin.py) instead of the containing directory.
2. Verify the path with `ls -la <path>` to confirm it is a file, not a directory.
3. Check that any variable or script building the path appends a filename component.

Example fix

# before
pytest -p myplugin_dir/

# after
pytest -p myplugin_dir/myplugin.py

import os

def ensure_is_filename(path: str, optname: str) -> str:
    if os.path.isdir(path):
        raise ValueError(f"{optname} must be a filename, but '{path}' is a directory")
    if not os.path.isfile(path):
        raise FileNotFoundError(f"{optname}='{path}' does not exist or is not a file")
    return path

When it happens

Trigger: Passing a directory path to a pytest CLI option that expects a filename (e.g., a plugin registration or ini-override argument wired through filename_arg). os.path.isdir(path) returns True, triggering the error.

Common situations: Pointing an option at a project root or a package directory instead of a specific .py file. Tab-completion accidentally selecting a directory, or a config script computing a path incorrectly.

Related errors

• {optname} must be a directory, given: {path}
• option dest {dest!r} already used by {option.names()!r} (thi
• Directory '{rootdir}' not found. Check your '--rootdir' opti
• plugin {name} cannot be disabled
• Blocking conftest files using -p is not supported: -p no:{na

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