Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Concurrency, Network and Tools

The subprocess module

Reference for Python's subprocess module: run(), capture_output, check, timeout, Popen, pipes, shell=False and avoiding shell injection safely.

The subprocess module starts other programs from Python, waits for them, and gives you their exit code, standard output and standard error. For almost every task the one function you need is subprocess.run(); Popen is the lower-level class behind it for streaming and pipelines.

Pass the command as a list of strings (["git", "status"]), not one string. That way no shell is involved, quoting is never an issue, and user-supplied text cannot inject extra commands.

Python
import subprocess

result = subprocess.run(["python", "--version"], capture_output=True, text=True)
print(result.stdout)

Try it

The browser runner cannot start operating-system processes, so the code below only shows what the calls look like and what happens when they are impossible. Run it to see the error Pyodide reports; on a real computer the commented lines show the typical results.

Python What happens in the browser

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Typical use on your own machine (read-only):

Python
import subprocess

# Capture text output and fail loudly on a non-zero exit code
result = subprocess.run(
    ["git", "log", "--oneline", "-3"],
    capture_output=True,
    text=True,
    check=True,
    timeout=10,
)
print(result.stdout)

# Feed standard input
upper = subprocess.run(["tr", "a-z", "A-Z"], input="hello", capture_output=True, text=True)
print(upper.stdout)          # HELLO

# Handle errors
try:
    subprocess.run(["ls", "/no/such/folder"], check=True, capture_output=True)
except subprocess.CalledProcessError as err:
    print(err.returncode, err.stderr)
except FileNotFoundError:
    print("program not installed")
except subprocess.TimeoutExpired:
    print("took too long")

Syntax

Python
subprocess.run(args, *, stdin=None, input=None, capture_output=False,
               shell=False, cwd=None, timeout=None, check=False,
               encoding=None, errors=None, text=None, env=None)
Name Description
args A list of strings (preferred) or, with shell=True, a single command string.
capture_output True collects stdout and stderr (shorthand for stdout=PIPE, stderr=PIPE).
input Data sent to the process's standard input. Must be str with text=True, otherwise bytes.
text True decodes output to str; the default gives bytes. universal_newlines is the old name.
check True raises CalledProcessError when the exit code is not 0.
timeout Seconds to wait. The process is killed and TimeoutExpired is raised when it expires.
cwd, env Working directory and environment variables for the child. env replaces the whole environment.
shell True runs the command through the system shell. Avoid unless you need shell features.

Return value: a CompletedProcess object with args, returncode, stdout and stderr (both None unless captured), plus check_returncode().

Raises: FileNotFoundError (program missing), PermissionError, CalledProcessError, TimeoutExpired.

Usage notes

  • Never build a command string from user input and run it with shell=True. A value such as x; rm -rf ~ becomes a second command. With a list and shell=False it is just one odd argument.
  • stdout=None means "inherit". Without capture_output, the child writes to your terminal and result.stdout is None.
  • Pipes can deadlock. With Popen, reading stdout while the child blocks writing stderr can hang. Use communicate() or run(), which read both safely.
  • Large output is held in memory with capture_output. For huge streams, use Popen and read line by line.
  • Check exit codes. A non-zero returncode does not raise unless you pass check=True.
  • Popen starts the process without waiting. Use proc.communicate(), proc.wait(), proc.poll(), proc.terminate() and proc.kill() to manage it, ideally inside with subprocess.Popen(...) as proc:.
  • Portability. Commands like ls or echo are not programs on Windows (echo is a shell built-in). Use sys.executable to launch Python itself.
  • Older helpers check_output(), call() and check_call() still work, but run() covers them.
  • Not available in Pyodide, WebAssembly sandboxes and some restricted hosts.