← All commands
THE COMMAND REFERENCE

timeout

Run a command and stop it if it takes too long.

Last updated

Portable / common

Implementation-level reference; examples are not certified for every installed version.

Overview

timeout runs a command and stops it after a time limit, so a stuck command cannot hang a script forever. It sends the command a signal, TERM by default, when the time is up. On GNU the exit status is 124 when the limit was hit, and otherwise the command's own status.

Background

timeout is part of GNU coreutils and is also an applet in BusyBox. macOS does not ship it. They agree on the form timeout SECONDS COMMAND.

Examples

Run a command that finishes in time; its output is passed through:

timeout 5 echo hi

Stop a command that runs too long; the shell shows that it did not succeed:

timeout 1 sleep 5 || echo stopped

Use the command's own exit status when it finishes in time:

timeout 5 sh -c 'exit 3'; echo $?

Send a different signal with -s; here the stronger KILL, and the shell's own message about it is hidden:

{ timeout -s KILL 1 sleep 5; } 2> /dev/null || echo killed

Options

-s
Send this signal instead of TERM when the time is up.

Common mistakes

A command can ignore TERM, in which case it keeps running; use -s KILL or GNU's -k to follow up. timeout stops the command it started, but the command's children may survive. The exit status for a timeout is 124 on GNU, and may be different on other implementations, so test for "not 0" unless you know which you have. The time can have a suffix such as m for minutes in GNU.

Portability

This page has no Apple view: macOS has no timeout; a script there can install gtimeout from GNU coreutils. Only whole seconds and -s are in the Common examples. The Common examples were executed on GNU coreutils 9.11 and BusyBox 1.37.0 (see the development guide for the exact check).

References

Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.