← Full reference

timeout and sleep

Limit how long a command runs (timeout -s -k, code 124) and pause (sleep with units s, m, h, d)

timeout runs a command and, if it hasn't finished within the allotted time, sends it a signal (SIGTERM by default). You need it so that a hung curl, check or script doesn't hang forever — in cron, CI, wait loops. sleep simply waits for the given time; together they make the classic "check every second, but no longer than a minute" loop.

Syntax

timeout [options] duration command [arguments…]
sleep number[unit]…

Duration

SyntaxMeaning
5 or 5s5 seconds (seconds are the default)
0.5half a second — fractional numbers are allowed
2m / 1h / 1dminutes / hours / days
sleep 1m 30ssleep's multiple arguments add up: 90 seconds
sleep infinitywait forever (handy to keep a container from exiting)
timeout 0 …the limit is disabled

timeout options

OptionWhat it does
-s signalwhich signal to send when time runs out: TERM (default), INT, HUP, KILL or a number
-k timeif the command is still alive this long after the first signal — send SIGKILL
--preserve-statusreturn the command's own code (e.g. 143 = killed by SIGTERM) instead of 124
--foregrounddon't move the command to the background: it can read from the terminal and receive Ctrl+C; child processes are then not killed on timeout
-vreport to stderr which signal was sent

timeout exit codes

CodeWhen
the command's codethe command finished on its own in time
124time ran out and the command was sent a signal (other than KILL)
125an error in timeout itself (invalid option or duration)
126the command was found but can't be run (no x permission)
127the command wasn't found
137the command was killed by SIGKILL (-s KILL or -k fired): 128 + 9

Examples

# don't wait for the server's reply longer than 5 seconds
timeout 5 curl -s http://localhost:8080/health

# tell "timed out" from "failed"
timeout 10 ./check.sh
rc=$?
if [ "$rc" -eq 124 ]; then echo "timed out"; elif [ "$rc" -ne 0 ]; then echo "error $rc"; fi

# politely ask it to exit, kill it 5 seconds later
timeout -k 5 30 ./long-job.sh

# send the Ctrl+C signal instead of TERM (the program gets to save its state)
timeout -s INT 60 ./collector

# wait for a port to open, but no longer than 30 seconds
timeout 30 bash -c 'until ss -ltn | grep -q ":8080 "; do sleep 1; done'

# the same for a file
timeout 10 bash -c 'while [ ! -f /tmp/ready ]; do sleep 0.5; done' || echo "gave up waiting"

# pauses
sleep 2
sleep 0.2
sleep 1m 30s
sleep infinity &

# collect data for exactly 3 seconds
timeout 3 tail -f /var/log/syslog > sample.log

Pitfalls

  • Code 124 isn't the command's error. In set -e scripts and CI checks, timeout gives a non-zero code 124 when time runs out, even for a "normal" tail -f. Handle it explicitly: timeout 3 tail -f log || [ $? -eq 124 ].
  • Functions, aliases and builtins don't work. timeout 5 cd /tmp or timeout 5 my_function — "failed to run command", code 127: timeout only runs programs. Wrap them in bash -c '…'.
  • A signal can be ignored. If the command traps or ignores SIGTERM, it runs to completion, and timeout still returns 124. The safeguard is -k 5 (an extra SIGKILL) or -s KILL.
  • With -s KILL and -k the code is 137, not 124. Check both values.
  • timeout moves the command into a background process group. Interactive programs (a password prompt, read from the terminal) can't read input, and Ctrl+C doesn't reach them. For those — --foreground.
  • Inside a pipeline only one element is limited. cat big | timeout 1 head … limits head; cat gets SIGPIPE (code 141) after it exits. To limit the whole pipeline — timeout 1 bash -c 'a | b'.
  • sleep 1x and sleep -1 are an error with code 1, not a pause. Units are only s, m, h, d.
  • A while sleep 1 loop without timeout or a counter can wait forever if the condition is never met.

See also

background · kill · exit-codes · conditions-loops · curl · date