To limit how long a Linux command runs, GNU timeout can start it with a deadline and send a termination signal when that deadline expires. Its default timeout result is exit status 124, not success. Capturing that result immediately lets you distinguish a bounded wait from a command that completed normally.
This is useful for occasional diagnostic commands that might hang. It is not a transaction rollback mechanism, and terminating a command does not undo changes it already made. Start with harmless examples before wrapping anything that writes data.
Check which timeout implementation you have
These examples use GNU Coreutils, commonly installed on Linux. Check the implementation and its locally available help first:
timeout --version
timeout --helpIf the command is missing or the help describes a different implementation, do not assume every option below is supported. Minimal systems and containers can provide different tools. No administrator privileges are needed for these demonstrations.
Run a harmless deadline example
In Bash, paste this block as separate lines. The child command only waits; it does not modify files:
timeout 1s sleep 5
status=$?
printf 'exit status: %s\n' "$status"With GNU timeout, expect status 124 because the one-second limit is reached before the five-second sleep finishes. The default signal is TERM. Actual timing depends on system conditions, so this is not a precision scheduling tool.
Capture $? immediately. Running an unrelated command before the assignment replaces the status you intended to inspect. For a successful comparison, run:
timeout 5s sleep 0.1
status=$?
printf 'exit status: %s\n' "$status"This should report zero: the child finishes before its deadline. The suffix s means seconds; GNU timeout also accepts minutes, hours and days. A duration of zero disables the associated timeout, which is usually the opposite of what a beginner intends.
Handle a timeout without discarding other failures
A small wrapper can distinguish the deadline result while preserving failures for its caller. This Bash example is deliberately self-contained:
if timeout 1s sleep 5; then
status=0
else
status=$?
fi
case "$status" in
0) printf 'Command finished successfully\n' ;;
124) printf 'Time limit reached; inspect before retrying\n' >&2 ;;
*) printf 'Command or wrapper failed: %s\n' "$status" >&2 ;;
esac
exit "$status"Save that block as a script and run it with Bash rather than pasting its final exit into a terminal you want to keep open. The conditional also makes the capture explicit in scripts using set -e. Do not append || true simply to make monitoring look green.
Status 124 is the documented default timeout indicator, but a child could itself return 124. It is not universally unique proof of the cause. Preserve relevant error output and command context when diagnosing a real program.
Understand escalation and status limitations
Some programs ignore TERM or need time to clean up. GNU timeout offers --kill-after for escalation. For example, timeout --kill-after=2s 5s sleep 20 sends TERM after the main five-second limit and allows an additional two-second interval before KILL if needed. That interval starts when the initial signal is sent, not when the command starts.
KILL prevents normal cleanup. Never add it casually around package changes, backups or database operations. The documented result 137 can mean the managed command or timeout itself received KILL; that number alone does not distinguish them. Statuses 125, 126 and 127 respectively describe timeout’s own failure, a command that cannot be invoked, and a command that cannot be found.
Avoid --preserve-status when your wrapper relies on the default 124 convention: it changes timeout reporting. The --foreground option also changes supervision behaviour; the manual specifically warns that children are not timed out in that mode.
Before retrying: a short checklist
- Was the deadline realistic for this workload?
- Did the command produce partial output or partially complete a write?
- Does the tool offer its own safer network or operation timeout?
- Have you recorded stderr and the immediate exit status?
If a diagnostic appears stuck on a different filesystem view, see comparing process mount information rather than repeatedly increasing a deadline.
FAQ: Does a timeout mean nothing happened?
No. It establishes a supervision outcome, not an application-level rollback or proof that no remote operation occurred. Reconcile the actual result before retrying a command that can create resources or change data.
Source: GNU Coreutils manual source, timeout invocation section, covering signals, durations and exit statuses.
Safety: 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.
