pypa/pip · error · BadCommand

Cannot find command {cls.name!r} - do you have {cls.name!r}

Error message

Cannot find command {cls.name!r} - do you have {cls.name!r} installed and in your PATH?

What it means

Raised by `VCS.run_command` when spawning the VCS executable raises `FileNotFoundError` (ENOENT) — the executable is simply not installed or not on PATH. pip re-raises it as `BadCommand` with an install hint, since without the VCS binary no clone/checkout can proceed.

Source

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

            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."
            )

    @classmethod
    def is_repository_directory(cls, path: str) -> bool:

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Install the missing VCS tool: `apt-get install git` / `yum install subversion` / `brew install mercurial`.
2. Verify with `which git` (or `svn`, `hg`, `bzr`) that the binary resolves on PATH.
3. If installed but not found, add its directory to PATH (e.g. `/usr/local/bin`, `/opt/homebrew/bin`).
4. In Docker/CI, add the VCS package to the image build.

Example fix

# before (in Dockerfile)
RUN pip install git+https://github.com/org/repo.git
# -> FileNotFoundError -> BadCommand

# after
RUN apt-get update && apt-get install -y git \
 && pip install git+https://github.com/org/repo.git

import shutil, sys

def ensure_vcs_available(name: str) -> None:
    if shutil.which(name) is None:
        raise EnvironmentError(
            f"{name!r} not found on PATH; install it (e.g. apt-get install {name})"
        )

# before any pip VCS op:
ensure_vcs_available("git")

null

from pip._internal.exceptions import BadCommand
try:
    pip_api_call(...)
except BadCommand as e:
    # prompt user to install the missing VCS
    ...

When it happens

Trigger: Any pip install/freeze operation against a `git+`/`svn+`/`hg+`/`bzr+` URL when the corresponding `git`/`svn`/`hg`/`bzr` binary cannot be found by the OS via PATH lookup.

Common situations: Minimal Docker/CI images that omit git/svn; fresh OS installs without dev tools; relying on a virtualenv that does not provide system VCS binaries; SSH-ing into a server where the VCS is only installed for a different user.

Related errors

• Cannot find command {cls.name!r} - invalid PATH
• No permission to execute {cls.name!r} - install it locally,
• Could not locate Python interpreter {general_options.python}
• Could not determine appropriate file.
• Editor Subprocess exited with exit code {e.returncode}

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