Skip to main content

exec.which

The exec.which function returns the absolute path of the executable that exec.run would start for a program name, or None when no executable matches. Use it to check a prerequisite before running it, or to branch on which tool is available.

Usage​

exec.which(name)

Arguments​

name

Required. The program name, such as "terraform". A name that contains a path separator, such as "./scripts/deploy", resolves relative to the script's working directory instead of being searched on PATH. An empty name is an error.

Returns​

The absolute path of the executable as a string, or None when nothing matches.

The search uses the same environment as exec.run: the PATH of the effective execution environment, including the directories that dependencies.tools adds, and PATHEXT on Windows. It does not consult the shell, so aliases and shell functions are never found.

Examples​

Check prerequisites before running anything​

missing = [tool for tool in ["docker", "python3"] if not exec.which(tool)]
if missing:
    errors.build("Missing prerequisites: " + ", ".join(missing)).with_hint("Install them or pin them with dependencies.tools.").fail()

Prefer one tool over another​

tf = exec.which("tofu") or exec.which("terraform")
if not tf:
    fail("neither tofu nor terraform is installed")
exec.run([tf, "version"])

Report where a tool came from​

jq = exec.which("jq")
if jq:
    ui.info("Using " + jq)
else:
    ui.info("jq is not installed")

Errors​

  • An empty name, a missing argument, or an argument that is not a string fails with an argument error.
  • A name that does not resolve is not an error: the function returns None.

Related​