How to Execute System Commands in Python

By the end of this page, you will understand how Python runs external commands, when to use the subprocess module, how to pass arguments safely, how to capture output, and how to avoid common mistakes such as shell injection or incorrect argument formatting.

Running a system command from Python means starting another program from your Python script.

In Python, the standard and recommended way to do this is with the subprocess module. It lets your code:

• start another program
• pass command-line arguments
• wait for it to finish
• read its output
• check its exit status

This matters because real programs often need to interact with other tools. For example:

• a Python script may call git
• a deployment script may run docker or npm
• a data pipeline may execute a compression tool
• a utility script may open another application

The key idea is that Python is not "typing into a terminal" the way a human does. Instead, it asks the operating system to start another process.

The modern recommendation is:

• use subprocess.run() for most simple cases
• use subprocess.Popen() for more control
• avoid older approaches like os.system() unless you specifically need its limited behavior

One of the most important parts of this topic is safety. If you build command strings from user input and pass them through a shell, you can accidentally create serious security problems. That is why Python usually works best when you pass the command and its arguments as a list.

Think of your Python script as a manager in an office.

• Python is the manager.
• An external command is another worker.
• subprocess.run() is the manager giving that worker a task.
• The argument list is the instruction sheet.
• The return code is the worker reporting success or failure.
• Captured output is the written report the worker brings back.

If you send the instructions clearly as separate pieces, the task is usually done correctly. If you send one big messy string through a shell, the shell has to interpret it first, which adds complexity and risk.

Basic syntax

The most common way to run a command is:

import subprocess

subprocess.run(["command", "arg1", "arg2"])

This starts the program and waits for it to finish.

Example: run a simple command

import subprocess

subprocess.run(["echo", "Hello from Python"])

This runs the echo command with one argument.

Capture output

import subprocess

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

print(result.stdout)
print(result.returncode)

What this does

• capture_output=True collects standard output and standard error
• text=True returns strings instead of bytes
• result.stdout contains normal output
• result.stderr contains error output

Consider this example:

import subprocess

result = subprocess.run(
    ["echo", "Python subprocess"],
    capture_output=True,
    text=True
)

print("Return code:", result.returncode)
print("Output:", result.stdout)

Here is what happens step by step:

1. Python imports the subprocess module.
2. subprocess.run() is called.
3. Python asks the operating system to start the echo program.
4. The program receives one argument: Python subprocess.
5. Because capture_output=True, the program's output is saved instead of printed directly to the terminal.
6. Because text=True, the saved output is decoded into a normal Python string.
7. The command finishes.
8. Python stores the result in result.
9. result.returncode is printed. For a successful command, this is usually 0.
10. result.stdout is printed, which contains the command output.

A typical output might be:

Running external commands is common in practical Python work.

Automation scripts

A script may:

• create folders
• copy files
• compress logs
• run backup tools

Development tools

Python can call tools such as:

• git to inspect repositories
• pytest to run tests
• npm to build frontend assets
• docker to start containers

Data processing

A Python program may use existing command-line tools for:

• image conversion
• video encoding
• file decompression
• database export/import

System administration

Admins often use Python to:

• restart services
• inspect processes
• query system information
• schedule maintenance tasks

Integration with legacy tools

Sometimes a company already has reliable command-line programs. Python can act as the glue code that calls them and processes their results.

In real projects, developers usually wrap command execution in small helper functions instead of scattering subprocess.run() everywhere.

Common patterns

Guard clauses

Check that needed values exist before running the command.

import subprocess


def show_file(path):
    if not path:
        raise ValueError("path is required")

    return subprocess.run(["cat", path], capture_output=True, text=True, check=True)

Early failure with check=True

This makes scripts fail immediately when an important command does not succeed.

subprocess.run(["git", "status"], check=True)

Validation before execution

If arguments come from configuration or users, validate them first.

allowed_envs = {"dev", "staging", "prod"}
env = "dev"

 env   allowed_envs:
     ValueError()

1. Using one command string when a list is safer

Broken approach:

import subprocess

filename = "my file.txt"
subprocess.run("cat " + filename, shell=True)

Problems:

• spaces can break the command
• shell metacharacters may be interpreted
• user input can become dangerous

Better approach:

import subprocess

filename = "my file.txt"
subprocess.run(["cat", filename])

2. Forgetting that shell built-ins are different

Some commands are not standalone programs. For example, dir on Windows is usually handled by cmd.

import subprocess

subprocess.run(["dir"])

This may fail because dir is not an executable program.

Use:

subprocess.run(["cmd", "/c", "dir"])

3. Not capturing output when you need it

subprocess.run() vs

import subprocess

Run a command

subprocess.run(["command", "arg1", "arg2"])

Capture output as text

result = subprocess.run(
    ["command", "arg1"],
    capture_output=True,
    text=True
)

print(result.stdout)
print(result.stderr)
print(result.returncode)

Raise an error if the command fails

subprocess.run(["command"], check=True)

Run in a specific directory

subprocess.run(["command"], cwd="/path/to/folder")

Use custom environment variables

import os

env = os.environ.copy()
env["DEBUG"] = "1"
subprocess.run(["command"], env=env)

When to use

How do I run a terminal command in Python?

Use subprocess.run():

import subprocess
subprocess.run(["echo", "hello"])

What is the best way to execute a shell command in Python?

Usually, subprocess.run() with a list of arguments is the best choice because it is safer and easier to control.

How do I capture command output in Python?

Use capture_output=True and text=True:

result = subprocess.run(["echo", "hello"], capture_output=True, text=True)
print(result.stdout)

What does shell=True do in Python?

It runs the command through the system shell. This allows shell features, but it can introduce security and quoting problems.

How do I know whether a command succeeded?

Check result.returncode, or use check=True to raise an exception automatically on failure.

Why does my command work in the terminal but not in Python?

• subprocess.Popen — related because it provides lower-level process control than subprocess.run().
• os.system — related as an older way to run commands, useful for comparison.
• standard input, output, and error — important because external commands communicate through these streams.
• exit codes — related because commands report success or failure with return codes.
• environment variables — useful when external programs depend on specific settings.
• working directory — related because commands often behave differently depending on where they are run.
• exception handling — important for dealing with failed commands safely.
• shell injection — closely related because command execution can become insecure if input is not handled safely.