Tools and workflows

Python subprocess.run: arguments, output, and timeouts

Run a local command from Python, capture stdout and stderr, and tell an exit error apart from a timeout or an executable that never started.

subprocess.run() starts a command and waits for it to finish. Pass the executable and arguments as separate list items. Set capture_output=True if you need stdout and stderr, check=True if a nonzero exit should raise an exception, and timeout if you need to limit how long the call waits for the child.

Run a local Python command and capture its output

This short example starts the same Python interpreter in a child process. It does not require an external package.

import subprocess
import sys

result = subprocess.run(
    [sys.executable, "-c", "print('worker ready')"],
    capture_output=True,
    text=True,
    check=True,
    timeout=5,
)
print(result.stdout.rstrip())

The expected line is worker ready. The completed process object has a return code and the captured output streams. With text=True the streams are decoded as text. Specify a known encoding when the child documents one. Keep bytes if the output is binary or has no stable encoding.

Keep failure cases distinct

A missing executable can raise FileNotFoundError before there is a process result. A started process can exit with a nonzero status, which raises CalledProcessError when checking is enabled. An overlong run can raise TimeoutExpired. A failure to launch a program should never be recorded as a completed run with zero results.

Some commands use distinct nonzero exit codes for ordinary outcomes. Read the documented exit contract. When a documented exit code is meaningful, inspect returncode and handle the value intentionally. Keep standard error available for diagnosis and avoid including privileged or private output in a general log.

Supply arguments explicitly

Use an argument list and keep the default shell=False for ordinary executables. A path that contains a space is one list element. A pipe symbol in a list element does not turn the invocation into a command pipeline. Restrict any value supplied by an outside caller to the intended field. Arguments can still cause harm if the selected executable treats that value as an option or destructive operation.

Set cwd when a tool needs a specific working directory. If a terminal run works and the wrapper fails, compare the executable path, working directory, and available environment. You may be invoking a different copy of the program or skipping a shell preparation step your interactive session performed.

Verify a failure as well as a success

Replace the child source argument in the local example with import sys; sys.exit(7). With check=True the caller sees a CalledProcessError carrying that code. Compare this with an unavailable fixture executable, which cannot return a child status. A timeout in a known sleeping child is yet another result. Verify these with the same interpreter and short, predictable input.

For a real wrapper, choose which failures propagate. A build can stop if its compiler fails. An inventory job might call independent checks and still report results from those that completed. Both can use the same API. A concise error should tell the caller what remains incomplete and whether a previous good result is still available.

Keep the calling environment understandable

A child normally inherits the parent's environment. If you pass an explicit env mapping, you are selecting what the child receives. An empty or incomplete mapping can remove settings a tool expects. Start with the minimal documented needs, and test with the same account and working directory your job will use. If the child output seems different, compare the launch context before blaming parsing logic.

Plan for output size

Captured output sits in memory until the child finishes. That works for a version string or small report. For larger output, use a file destination with a size or retention policy. Some commands print ordinary progress to standard error. Use the exit status to interpret it. If you also need to manage the child during the run, see when to use Popen.

Check one known success, one expected failure, and a case where the command cannot start. A useful wrapper preserves the difference between a completed operation and a command that never ran.

Sources and further reading

Related reading

Browse Tools and workflows · Explore project tutorials

Search PythonProjects.org