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.
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.
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):
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
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 asx; rm -rf ~becomes a second command. With a list andshell=Falseit is just one odd argument. stdout=Nonemeans "inherit". Withoutcapture_output, the child writes to your terminal andresult.stdoutisNone.- Pipes can deadlock. With
Popen, readingstdoutwhile the child blocks writingstderrcan hang. Usecommunicate()orrun(), which read both safely. - Large output is held in memory with
capture_output. For huge streams, usePopenand read line by line. - Check exit codes. A non-zero
returncodedoes not raise unless you passcheck=True. Popenstarts the process without waiting. Useproc.communicate(),proc.wait(),proc.poll(),proc.terminate()andproc.kill()to manage it, ideally insidewith subprocess.Popen(...) as proc:.- Portability. Commands like
lsorechoare not programs on Windows (echois a shell built-in). Usesys.executableto launch Python itself. - Older helpers
check_output(),call()andcheck_call()still work, butrun()covers them. - Not available in Pyodide, WebAssembly sandboxes and some restricted hosts.
Related
os,shutil,systhreading,multiprocessing- Lessons: Command-line programs, Concurrency