Subprocess.check_output in Python

subprocess.check_output() runs a program with the arguments you provide and returns its standard output. Pass arguments as a list to capture a command’s result without building a shell command string.

Using subprocess.check_output() in Python

Use subprocess.check_output() when your script needs a command’s output and should treat a nonzero exit status as a failure. The function is part of Python’s subprocess module; it does not run commands in parallel.

Syntax and return behavior

An abbreviated call shape is subprocess.check_output(args, *, cwd=..., timeout=..., text=None, ...); this is not the complete function signature. args supplies the command and its arguments. cwd, timeout, and text are keyword arguments: cwd selects the child process’s working directory, timeout limits how long the call waits, and text controls whether captured output is decoded to text. The default for text is None, so output is bytes unless text mode is enabled. See the Python subprocess documentation for the full API reference.

By default, the returned value is bytes. Decode it when you need a Python string. With text=True, Python decodes captured output for you. This compact example asks the Python interpreter to print a fixed line, captures the bytes, decodes them as UTF-8, and writes the line to standard output.

import subprocess
import sys

output = subprocess.check_output(
    [sys.executable, "-c", "print('ready')"]
)
print(output.decode("utf-8"), end="")

ready

The argument list keeps the executable and its arguments separate. A call such as subprocess.check_output(["git", "status"]) captures Git’s standard output in the current directory.

Run Git commands with subprocess.check_output()

Run these calls from the repository you want to inspect. To read the current branch, use subprocess.check_output(["git", "rev-parse", "--abbrev-ref", "HEAD"], text=True).strip(). When the repository is in detached-HEAD state, Git reports HEAD instead of a branch name.

To list configured remotes and their URLs, use subprocess.check_output(["git", "remote", "-v"], text=True). To view staged, unstaged, and untracked changes, use subprocess.check_output(["git", "status"], text=True). These commands depend on Git being installed and the current working directory being inside the intended repository; set cwd to that repository path when needed.

Handle errors and choose between check_output() and run()

If the child process exits with a nonzero status, subprocess.check_output() raises CalledProcessError. Its returncode records the exit status, and its output attribute contains captured standard output. Standard error is not captured by default; pass stderr=subprocess.STDOUT if you want it combined with standard output.

A list of arguments does not require a shell. Avoid passing untrusted input to a command through shell=True, because shell interpretation can allow command injection; shell quoting alone is not a general safety fix.

Choose subprocess.check_output() for the focused task of capturing output and treating unsuccessful exits as errors. Choose subprocess.run() when you also need a CompletedProcess, more control over standard streams, or a choice about how to handle the exit status. For example, subprocess.run(args, capture_output=True, text=True, check=False) returns the status and captured streams for your code to inspect.