pytest-dev/pytest · error · UsageError

Directory '{rootdir}' not found. Check your '--rootdir' opti

Error message

Directory '{rootdir}' not found. Check your '--rootdir' option.

What it means

Raised when the --rootdir command-line argument points to a path that does not exist or is not a directory. pytest resolves --rootdir to an absolute path and checks is_dir(); a missing directory is rejected immediately rather than silently falling back.

Source

Thrown at src/_pytest/config/findpaths.py:342

        )
        if rootdir is None and rootdir_cmd_arg is None:
            for possible_rootdir in (ancestor, *ancestor.parents):
                if (possible_rootdir / "setup.py").is_file():
                    rootdir = possible_rootdir
                    break
            else:
                if dirs != [ancestor]:
                    rootdir, inipath, inicfg, _ = locate_config(invocation_dir, dirs)
                if rootdir is None:
                    rootdir = get_common_ancestor(
                        invocation_dir, [invocation_dir, ancestor]
                    )
                    if is_fs_root(rootdir):
                        rootdir = ancestor
    if rootdir_cmd_arg:
        rootdir = absolutepath(os.path.expandvars(rootdir_cmd_arg))
        if not rootdir.is_dir():
            raise UsageError(
                f"Directory '{rootdir}' not found. Check your '--rootdir' option."
            )

    ini_overrides = parse_override_ini(override_ini)
    inicfg.update(ini_overrides)

    assert rootdir is not None
    return rootdir, inipath, inicfg, ignored_config_files


def is_fs_root(p: Path) -> bool:
    r"""
    Return True if the given path is pointing to the root of the
    file system ("/" on Unix and "C:\\" on Windows for example).
    """
    return os.path.splitdrive(str(p))[1] == os.sep

View on GitHub (pinned to 98b357f69e)

Solutions

Verify the path exists: ls /path/to/rootdir before running pytest.
Use a path relative to the invocation directory or an absolute path you have verified.
Remove --rootdir entirely to let pytest auto-determine the rootdir from config/args.
Ensure CI checks out the directory structure your --rootdir assumes.

Example fix

# before
pytest --rootdir /home/me/wrongdir

# after
pytest --rootdir /home/me/myproject
# or omit it
pytest

Defensive patterns

Strategy: validation

Validate before calling

import os
from pathlib import Path
def validate_rootdir(path_str: str) -> Path:
    p = Path(os.path.expandvars(path_str)).resolve()
    if not p.is_dir():
        raise FileNotFoundError(f"Directory '{p}' not found. Check your '--rootdir' option.")
    return p

Type guard

from pathlib import Path
def rootdir_exists(path_str: str) -> bool:
    return Path(path_str).expanduser().is_dir()

Prevention

Verify the --rootdir path with ls before invoking pytest.
Prefer relative paths anchored at the invocation directory or use absolute verified paths.
Omit --rootdir to let pytest auto-detect from config files.

When it happens

Trigger: Running pytest --rootdir /nonexistent/path, or --rootdir with a relative path that resolves outside the current working directory, or pointing --rootdir at a file rather than a directory. The check at line 339-344 fails is_dir().

Common situations: Typing the wrong path; using a path relative to a different working directory; pointing --rootdir at a file; CI environments where the expected directory isn't checked out; renamed/moved project directories.

Related errors

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