pypa/pip · error · BadCommand

Cannot find command {cls.name!r} - invalid PATH

Error message

Cannot find command {cls.name!r} - invalid PATH

What it means

Raised by `VCS.run_command` when invoking the VCS executable raises `NotADirectoryError`. This means an entry in the `PATH` environment variable resolves to something that is not a directory, so the OS cannot traverse it to find the executable. pip wraps it as a `BadCommand` so the failure surfaces as a configuration problem with PATH rather than an unhandled OS exception.

Source

Thrown at src/pip/_internal/vcs/versioncontrol.py:651

        cmd = make_command(cls.name, *cmd)
        if command_desc is None:
            command_desc = format_command_args(cmd)
        try:
            return call_subprocess(
                cmd,
                show_stdout,
                cwd,
                on_returncode=on_returncode,
                extra_ok_returncodes=extra_ok_returncodes,
                command_desc=command_desc,
                extra_environ=extra_environ,
                unset_environ=cls.unset_environ,
                spinner=spinner,
                log_failed_cmd=log_failed_cmd,
                stdout_only=stdout_only,
            )
        except NotADirectoryError:
            raise BadCommand(f"Cannot find command {cls.name!r} - invalid PATH")
        except FileNotFoundError:
            # errno.ENOENT = no such file or directory
            # In other words, the VCS executable isn't available
            raise BadCommand(
                f"Cannot find command {cls.name!r} - do you have "
                f"{cls.name!r} installed and in your PATH?"
            )
        except PermissionError:
            # errno.EACCES = Permission denied
            # This error occurs, for instance, when the command is installed
            # only for another user. So, the current user don't have
            # permission to call the other user command.
            raise BadCommand(
                f"No permission to execute {cls.name!r} - install it "
                f"locally, globally (ask admin), or check your PATH. "
                f"See possible solutions at "
                f"https://pip.pypa.io/en/latest/reference/pip_freeze/"
                f"#fixing-permission-denied."

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Inspect `echo $PATH` and remove any entry that is not an existing directory (`for d in ${PATH//:/ }; do [ -d "$d" ] || echo "bad: $d"; done`).
2. Re-activate your virtualenv or fix the activation script so PATH points to real directories.
3. Restore PATH to the system default and re-add only valid bin directories.

Example fix

# before
export PATH=/usr/local/bin/git:/usr/bin:/bin   # /usr/local/bin/git is a file

# after
export PATH=/usr/local/bin:/usr/bin:/bin

import os

def validate_path_dirs() -> list[str]:
    bad = [d for d in os.environ.get("PATH", "").split(os.pathsep) if d and not os.path.isdir(d)]
    if bad:
        raise EnvironmentError(f"PATH contains non-directory entries: {bad}")
    return bad

null

null

When it happens

Trigger: Any pip VCS operation calls `run_command([cls.name, ...])` (git/svn/hg/bzr) and `call_subprocess` raises `NotADirectoryError` because a PATH component is a file, a broken symlink, or a stale mountpoint.

Common situations: A corrupted/mis-set `PATH` (e.g. `PATH=/usr/bin/git:/bin` where a component is a file not a dir); a stale NFS/FUSE mount that previously held the bin directory; a virtualenv whose `bin` was replaced by a symlink to a file; shell rc files appending non-directory entries.

Related errors

• Cannot find command {cls.name!r} - do you have {cls.name!r}
• unexpected show-ref line: {line!r}
• Sorry, {url!r} is a malformed VCS url. The format is <vcs>+<
• The URL {url!r} has an empty revision (after @) which is not
• No permission to execute {cls.name!r} - install it locally,

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/af5c0b8f9689a3a5.json. Report an issue: GitHub.