`subprocess`

The Python subprocess module allows you to spawn new processes, connect to their input, output, and error pipes, and obtain their return codes. It’s a powerful tool for running and controlling external programs within a Python script.

Here’s a quick example:

Python
      
>>> import subprocess

>>> result = subprocess.run(
...     ["echo", "Hello, World!"], capture_output=True, text=True
... )

>>> result.stdout
'Hello, World!\n'

Key Features

Runs and controls external processes
Captures standard output and error streams
Supports for piping data to and from processes
Checks process return codes

Frequently Used Classes and Functions

Object	Type	Description
`subprocess.run()`	Function	Runs a command and waits for it to complete
`subprocess.Popen`	Class	Executes a child program in a new process
`subprocess.PIPE`	Constant	Uses for piping data between processes
`subprocess.CompletedProcess`	Class	Represents a process that has finished executing
`subprocess.check_output()`	Function	Runs a command and returns its output

Examples

Running a simple command and capturing its output:

Python
      
>>> result = subprocess.run(["ls", "-l"], capture_output=True, text=True)
>>> print(result.stdout)

Executing a command and checking its return code:

Python
      
>>> result = subprocess.run(["false"], capture_output=True)
>>> result.returncode
1

Capturing the output:

Python
      
        
      
    
>>> output = subprocess.check_output(
...     ["echo", "Hello from .check_output()"], text=True
... )
>>> output
'Hello from .check_output()'

Using a Popen object for fine-grained control over input/output (I/O) streams:

Python
      
>>> process = subprocess.Popen(
...     ["cat"], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True
... )

>>> output, _ = process.communicate("Hello from Popen!")
>>> output
'Hello from Popen!'

Common Use Cases

Automating shell command execution from Python
Capturing and processing the output of shell commands
Handling error codes returned by processes
Piping data between Python and external commands

Real-World Example

Suppose you need to automate the process of converting Markdown files to HTML using the pandoc command. You can use the subprocess module to run pandoc from your Python script:

Python
      
        
      
    
>>> from pathlib import Path
>>> import subprocess

>>> # Create a sample Markdown file
>>> input_path = Path("sample.md")
>>> input_path.write_text("# Hello, World!\n\nThis is a *Markdown* file.")
43

>>> output_path = Path("sample.html")

>>> try:
...     result = subprocess.run(
...         ["pandoc", str(input_path), "-o", str(output_path)],
...         capture_output=True,
...         text=True,
...         check=True,
...     )
...     print("Conversion successful!\n")
...     print("Generated HTML:\n")
...     print(output_path.read_text())
... except subprocess.CalledProcessError as e:
...     print("Conversion failed:")
...     print(e.stderr)
... finally:
...     input_path.unlink(missing_ok=True)
...     output_path.unlink(missing_ok=True)
...
Conversion successful!

Generated HTML:

<h1 id="hello-world">Hello, World!</h1>
<p>This is a <em>Markdown</em> file.</p>

In this example, you use the subprocess module to automate the Markdown-to-HTML conversion process and handle any errors that might occur. Note that if you don’t have pandoc installed, then you’ll get a FileNotFoundError exception.

The subprocess Module: Wrapping Program With Python

Tutorial

The subprocess Module: Wrapping Programs With Python

In this tutorial, you'll learn how to leverage other apps and programs that aren't Python, wrapping them or launching them from your Python scripts using the subprocess module. You'll learn about processes all the way up to interacting with a process as it executes.

intermediate

For additional information on related topics, take a look at the following resources: