If a Python automation script waits forever for an external command, add a timeout to subprocess.run() and handle the timeout separately from an unsuccessful exit. This prevents one stuck command from silently holding up the rest of a scheduled workflow. It does not make an unsafe operation safe to repeat.
This walkthrough uses harmless Python child processes instead of a backup, deployment or production service. You need Python 3 and a terminal. The examples assume you save the code as a local script and launch it with python3 filename.py.
Choose a bounded command interface
Pass the executable and arguments as a list. Leave shell=False, the default, so shell punctuation is not interpreted as a command pipeline. Use a trusted executable path for real automation, and validate any user-supplied arguments. Avoid constructing a shell command by concatenating input.
The Python documentation recommends run() for cases it can handle. Its timeout argument limits the wait associated with communication with the child. When that timeout expires, the child is killed and waited for before TimeoutExpired is raised. Process creation itself may not be interruptible, so this is not an absolute wall-clock deadline under every operating-system condition.
Build a small runner with distinct failure paths
import subprocess
import sys
def run_step(arguments, timeout_seconds):
try:
result = subprocess.run(
arguments,
timeout=timeout_seconds,
check=True,
capture_output=True,
text=True,
)
except subprocess.TimeoutExpired:
print('Command exceeded its time budget', file=sys.stderr)
return False
except subprocess.CalledProcessError as exc:
print(f'Command failed: exit {exc.returncode}', file=sys.stderr)
return False
except OSError as exc:
print(f'Command could not start: {exc}', file=sys.stderr)
return False
else:
print(result.stdout, end='')
return True
if __name__ == '__main__':
ok = run_step(
[sys.executable, '-c', 'print("health check finished")'],
timeout_seconds=5,
)
raise SystemExit(0 if ok else 1)This runner deliberately stops short of printing arbitrary command output on failure. External programs can include credentials, customer records or tokens in their diagnostics. In a real workflow, write only reviewed, redacted details to a restricted log. A false return must stop dependent work; do not upload a report or mark a backup successful after the prerequisite failed.
Exercise success, failure and timeout
First run the script unchanged. The child should print its short message and the wrapper should finish successfully. Next replace the child code with import sys; sys.exit(7). With check=True, a nonzero exit takes the command-failure branch. It is different from a timeout: the program finished but reported a problem.
Finally replace the child code with import time; time.sleep(3) and set timeout_seconds=1. This exercises the timeout branch without accessing the network or modifying files. These are expected behaviours for the example, not measurements from your environment. Record your actual exit codes and messages during testing.
Keep the child program single-process for this lab. A tool that launches other processes needs additional design: killing the immediate child does not establish that every descendant has stopped. Process-group handling is platform-specific and should be tested separately before using it with service managers or long-running jobs.
Set budgets and retries around the real task
Choose a budget from the operation’s documented behaviour and observed normal duration. A local status query and a remote inventory collection should not automatically share the same limit. If the application has its own connection and read timeouts, configure those too; the wrapper is an outer guard, not a substitute for application-level limits.
Do not automatically retry every timeout. A remote action might have completed even though your client stopped waiting. Before retrying a write, inspect the destination or use the service’s idempotency mechanism. For a read-only check, a small bounded retry policy with a delay may be appropriate. Cap the entire workflow, not just each individual attempt.
Also consider output volume. capture_output=True stores captured output in memory. For a command that can produce large logs, use a managed file or another deliberate output strategy rather than letting an unattended job consume unlimited memory.
Quick checklist and common questions
- Is the command read-only or safely repeatable?
- Does every failed prerequisite stop downstream actions?
- Have you tested a nonzero exit and a real timeout?
- Are logs redacted, bounded and access-controlled?
Should I use shell=True to fix a timeout? No. Shell selection and waiting limits solve different problems. Introducing a shell adds quoting and security considerations without fixing a slow remote service.
How do I roll back this change? Keep the previous script in version control and disable its schedule while testing. Restore the earlier revision if necessary, but investigate the original hang rather than removing all limits permanently. For broader workflow planning, see our automation security and backup review.
Source and safety note
Reference: official Python subprocess documentation, including run(), exceptions and timeout behaviour.
This tutorial is for educational purposes. Test carefully before production use. The site owner is not responsible for misuse, damage, data loss or production issues.
