# Python subprocess "FileNotFoundError: No such file or directory" in CI

> Fix subprocess.run() "FileNotFoundError: [Errno 2] No such file or directory: 'cmd'" in CI - the program isn’t on PATH, or shell=False got a shell string.

Source: https://latchkey.dev/learn/python/py-subprocess-filenotfounderror-no-such-file  
Updated: 2026-06-25

`subprocess` could not find the program you asked it to run. The error names the executable, not a data file - either the binary isn’t installed/on PATH, or you passed a whole shell command string with `shell=False`.

## Diagnose it: which Python, and which index?

A pip failure in CI is usually about the interpreter or the index rather than the package. Runners have several Pythons installed, and the one on PATH is not necessarily the one your virtualenv or your workflow selected.

```Terminal
which -a python python3 pip pip3
python -c "import sys; print(sys.executable, sys.version)"
pip config list
pip debug --verbose 2>/dev/null | grep -i "compatible tags" | head -5
```

> Compatible tags decide whether a wheel is usable. A package that installs from a wheel on your machine and builds from source in CI is a tag mismatch, and the resulting failure is a compiler error rather than a pip error.

## FAQ

### What causes Python subprocess "FileNotFoundError: no such file or directory" in CI?

There are 2 common causes: executable not installed or not on path and a shell command string with shell=false. The named command isn’t present in the CI image (or its directory isn’t on PATH), so the OS can’t exec it.

### How do I fix Python subprocess "FileNotFoundError: no such file or directory" in CI?

There are 2 fixes depending on which cause you have: install the program (and verify path) and pass a list, not a shell string. Work through them in order, since the first is the most common.

### What does Python subprocess "FileNotFoundError: no such file or directory" in CI actually mean?

A subprocess.run/Popen call raises FileNotFoundError: [Errno 2] No such file or directory: '<cmd>'.

### How do I stop Python subprocess "FileNotFoundError: no such file or directory" in CI happening again?

Install required external programs in the runner image. The prevention section lists 3 changes that keep it from recurring.

### Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt