pytest-dev/pytest · error · UsageError

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

Error message

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

What it means

When --rootdir is passed, pytest resolves it to an absolute path and checks is_dir(). If the directory does not exist, it raises UsageError pointing at the --rootdir option. pytest needs the rootdir to exist because it anchors test paths, cache, and output under it.

Solutions

Create the directory or correct the path; confirm with ls -d <rootdir>.
Use an absolute path that you have verified exists.
Drop --rootdir to let pytest infer the root from config location and common ancestors.

Example fix

// before
pytest --rootdir=build/out
// after
mkdir -p build/out && pytest --rootdir=$(pwd)/build/out

Defensive patterns

Strategy: validation

Validate before calling

import os, pathlib

def validate_rootdir(p: str) -> None:
    ap = pathlib.Path(os.path.abspath(os.path.expandvars(p)))
    assert ap.is_dir(), f'--rootdir does not exist: {ap}'

Type guard

null

Try / catch

null

Prevention

Pre-create output/root directories before invoking pytest.
Use absolute paths in CI to avoid cwd-relative surprises.

When it happens

Trigger: pytest --rootdir=/tmp/nonexistent; a relative rootdir resolved from an unexpected cwd; CI workspace layout differs from local.

Common situations: CI checkout missing the expected directory; typo in the path; running pytest from a different directory than assumed.

Related errors

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

Appendix: source

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

        )
        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 0d6fbdeffa)