subprocess Part 1: Run a Command

By the end of this lesson you can:

• Run an external command with subprocess.run.
• Pass arguments as a list — and explain why that's safer than a string.
• Read the result: returncode, and raise on failure with check=True.
• Recognise the shell=True command-injection trap and avoid it.

Lots of powerful tools have no Python library — but they all have a command line:

ffmpeg -i video.mov out.mp4        convert video formats
git commit -m "automated backup"   version control
pdftk in.pdf cat 1-5 output a.pdf  manipulate PDFs
ping -c 1 example.com              test connectivity

The basic call

import subprocess

result = subprocess.run(["python", "--version"])
print(result.returncode)        # 0 means success

Pass the command as a list: the program name first, then each argument as its own string element. subprocess.run launches it, waits, and returns a CompletedProcess object.

Why a list, not a string?

This is the heart of the lesson. Compare:

subprocess.run(["ls", "-l", "my folder"])     # ✅ safe: 3 clear arguments
subprocess.run("ls -l my folder")             # ✗ wrong: looks for a program literally named "ls -l my folder"

The list form passes arguments directly to the program, with no shell in between to misinterpret spaces, quotes, or special characters. "my folder" stays one argument. This is both safer and more predictable.

Checking success

result = subprocess.run(["git", "status"])
if result.returncode != 0:
    print("git failed!")

# or let it raise automatically:
subprocess.run(["git", "status"], check=True)   # raises CalledProcessError on non-zero

By convention, exit code 0 means success and anything else means failure (you saw this with sys.exit in Lesson 2). check=True turns a failure into a Python exception so you can't accidentally ignore it.

Handling "program not found"

try:
    subprocess.run(["ffmpeg", "-version"], check=True)
except FileNotFoundError:
    print("ffmpeg isn't installed or isn't on PATH")
except subprocess.CalledProcessError as e:
    print(f"ffmpeg ran but failed with code {e.returncode}")

Two different failures: FileNotFoundError (the program doesn't exist) vs. CalledProcessError (it ran but returned non-zero). Good automation distinguishes them.

The shell=True trap

A few handy options

subprocess.run(["pytest"], cwd="my_project")       # run in a specific folder
subprocess.run(["sleep", "10"], timeout=5)         # raises TimeoutExpired after 5s

Goal: a script that stages all changes and commits them with a timestamped message — but only if there's actually something to commit. (We'll read git's output properly next lesson; for now we use exit codes.)

import subprocess
from datetime import datetime

def run(cmd: list[str]) -> int:
    """Run a command in the current repo, return its exit code."""
    print(">", " ".join(cmd))
    return subprocess.run(cmd).returncode

def auto_commit() -> None:
    # 'git diff --quiet' exits 0 if NO changes, 1 if there ARE changes
    changes = subprocess.run(["git", "diff", "--quiet"]).returncode != 0
    staged  = subprocess.run(["git", "diff", "--cached", "--quiet"]).returncode != 0

    if not (changes or staged):
        print("Nothing to commit — working tree clean.")
        return

    run(["git", "add", "-A"])
    msg = "auto: " + datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    try:
        subprocess.run(["git", "commit", "-m", msg], check=True)
        print("Committed ✅")
    except subprocess.CalledProcessError:
        print("Commit failed — check git output above.")

auto_commit()

> git add -A
[develop abc1234] auto: 2026-05-28 14:30:12
 3 files changed, 21 insertions(+)
Committed ✅

Read the code

Notice every command is a list — ["git", "commit", "-m", msg] — so the message stays one argument even with spaces, and no shell can mangle it. We use exit codes cleverly: git diff --quiet returns non-zero when there are changes, which we read to decide whether to commit at all. check=True on the commit turns a failure into a catchable exception. This is a real script people run on a schedule — and you'll wire it to a timer in Lesson 35.

subprocess.run(["program", "arg1", "arg2"]) launches any command-line program and waits for it. Always pass arguments as a list — it's safer (no shell to misread spaces or run injected commands) and clearer. Check result.returncode (0 = success) or use check=True to raise on failure; catch FileNotFoundError (missing program) and CalledProcessError (non-zero exit) separately. Avoid shell=True, especially with any user input — that's the command-injection trap. Next lesson: capturing and reading the output.