How do you make subprocess.run raise on a failing command, and which exception carries the exit code?

## The default is silence `subprocess.run(args)` starts a child process, blocks until it finishes, and hands back a `subprocess.CompletedProcess`. That object's `returncode` attribute is the child's exit status — the small integer every program returns to the operating system when it ends. Zero means success; any other value means the program is telling you it did not do the job. By default `run` does not interpret that number at all. If you call `subprocess.run(["gzip", "report.pdf"])` and the file is missing, gzip exits non-zero, `run` returns normally, and your code sails on as though the file had been compressed. This is the single most common subprocess bug in real Python code, and it is silent by design: the library reports the outcome, it does not judge it. ## Two ways to turn a status into an exception The first is the `check=True` keyword argument: `subprocess.run(args, check=True)` raises `subprocess.CalledProcessError` the moment the child exits non-zero. The second is `CompletedProcess.check_returncode`, a method on the returned object that runs the same test and raises the same exception when you call it. They exist for different shapes of code. `check=True` is right when any failure is fatal and you want the exception at the call site. `check_returncode()` is right when you want the result object first — to log the captured stderr, to look at the numeric code, to decide that this particular non-zero value is acceptable — and only then to fail. ```python done = subprocess.run(cmd, capture_output=True, text=True) if done.returncode == 2: log.warning("tool reported differences: %s", done.stdout) else: done.check_returncode() ``` That pattern matters because not every non-zero status is an error. Plenty of command-line tools use exit codes as a channel: a comparison tool that exits 1 for "the inputs differ", a linter that exits 1 for "findings", a search tool that exits 1 for "no matches". Blanket `check=True` around such a tool turns normal output into a crash. ## What the exception actually carries `subprocess.CalledProcessError` is not just a marker. It holds the `returncode`, the `cmd` sequence exactly as you passed it, and — only if the corresponding stream was captured — `output` (aliased as `stdout`) and `stderr`. If you ran the child with its streams inherited from the parent, the exception's output fields are `None`, because the bytes went straight to your terminal and the library never saw them. That is why a diagnostic wrapper normally captures output: an error that says "command failed with exit status 1" is much less useful than one that can quote the tool's own message. ```python try: subprocess.run(cmd, check=True, capture_output=True, text=True) except subprocess.CalledProcessError as exc: raise RuntimeError(f"{exc.cmd[0]} failed ({exc.returncode}): {exc.stderr.strip()}") from exc ``` ## "Ran and failed" versus "never ran" These are two different worlds and interviewers probe the difference. If the executable cannot be found or is not executable, the failure happens while the parent is trying to start the child, and you get a `FileNotFoundError` or `PermissionError` — ordinary `OSError` subclasses, raised whether or not you passed `check=True`. Only once the program has actually run and exited does an exit status exist at all, and only then can `subprocess.CalledProcessError` be raised. Code that catches `Exception` around the call and reports "the command failed" flattens a configuration problem and a genuine tool error into the same log line. ## The older wrappers `subprocess.check_call` and `subprocess.check_output` predate `run` and behave as their names suggest: both raise `subprocess.CalledProcessError` on a non-zero status, and `check_output` additionally captures and returns standard output (as bytes unless you ask for text). They are thin wrappers over the same machinery and remain supported, but `run` with `check=True` and `capture_output=True` covers both and gives you a result object with `stderr` on it as well. `subprocess.CalledProcessError` derives from `subprocess.SubprocessError`, which is a useful base class if you want to catch the module's own failures without swallowing `OSError`. ## The judgement to carry into production code Make the raising form the default in whatever helper your codebase wraps around `subprocess`, and require callers to opt out for the tools whose exit codes carry information. The failure mode of forgetting `check=True` is invisible — a pipeline that reports success while producing nothing — and it is discovered a long way from where it was introduced.