Timeout Command in Linux

The timeout command runs a specified command and terminates it if it is still running after a given period of time. It is part of the GNU coreutils package, which is installed on virtually every Linux distribution.

This command is useful when you need to enforce a time limit on a command that does not have a built-in timeout option, such as ping , curl , or a long-running script.

This guide explains how to use the timeout command with practical examples.

Syntax #

The general syntax of the timeout command is:

timeout [OPTIONS] DURATION COMMAND [ARG]...

The DURATION can be a positive integer or a floating-point number, followed by an optional unit suffix:

• s — seconds (default)
• m — minutes
• h — hours
• d — days

When no unit is specified, the duration defaults to seconds. If the duration is set to zero, the timeout is disabled.

Basic Usage #

To terminate the ping command after five seconds:

timeout 5 ping 8.8.8.8

To set a timeout of five minutes:

timeout 5m ping 8.8.8.8

You can also use floating-point values. The following example sets a timeout of 1.5 minutes (90 seconds):

timeout 1.5m ping 8.8.8.8

If the command requires elevated privileges, prepend sudo before timeout:

sudo timeout 300 tcpdump -n -w data.pcap

Sending a Specific Signal #

By default, timeout sends the SIGTERM signal to the command when the time limit is reached. You can specify a different signal using the -s (--signal) option.

For example, to send SIGKILL to ping after one minute:

timeout -s SIGKILL 1m ping 8.8.8.8

You can also use the signal number instead of the name. The following command is equivalent:

timeout -s 9 1m ping 8.8.8.8

To list all available signals, use the kill -l command:

kill -l

Killing Stuck Processes #

Some processes catch or ignore the SIGTERM signal, which means they continue running after the initial termination signal is sent. To ensure the process is killed, use the -k (--kill-after) option followed by a time period.

When -k is used, timeout first sends SIGTERM when the time limit is reached. If the process is still running after the -k delay, it sends SIGKILL, which cannot be caught or ignored.

In the following example, timeout runs the command for one minute. If the process does not terminate after receiving SIGTERM, it is forcefully killed 10 seconds later:

timeout -k 10 1m ping 8.8.8.8

Preserving the Exit Status #

When the time limit is reached, timeout returns exit code 124. Otherwise, it returns the exit status of the managed command.

To return the exit status of the command even when a timeout occurs, use the --preserve-status option:

timeout --preserve-status 5 ping 8.8.8.8

Running in Foreground #

By default, timeout may use a separate process group for the managed command. If you need to run an interactive command that requires terminal input and proper signal handling, use the --foreground option:

timeout --foreground 5m ./script.sh

This is necessary for commands that read from the terminal, such as interactive prompts or editors.

Using timeout in Scripts #

The timeout command is commonly used in shell scripts to prevent commands from hanging indefinitely. Check the exit code to determine whether the command completed or was terminated:

#!/bin/bash

if timeout 30 curl -s -o /tmp/data.json https://api.example.com/data; then
    echo "Download completed successfully."
else
    if [ $? -eq 124 ]; then
        echo "Download timed out after 30 seconds."
    else
        echo "Download failed."
    fi
fi

Using timeout with Pipelines #

The timeout command applies only to the single command that follows it, not to an entire pipeline. To apply a timeout to a pipeline, wrap it in bash -c:

timeout 30 bash -c 'curl -s https://example.com | grep "pattern"'

Without the bash -c wrapper, timeout would only apply to curl, and grep would continue waiting for input even after curl is terminated.

Quick Reference #

FAQ #

What exit code does timeout return?
It returns 124 when the time limit is reached. If the command finishes before the timeout, it returns the exit code of that command. If timeout itself encounters an error, it returns 125, 126, or 127.

What is the difference between SIGTERM and SIGKILL?
SIGTERM (signal 15) asks the process to terminate gracefully — the process can catch it and clean up before exiting. SIGKILL (signal 9) forcefully terminates the process immediately and cannot be caught or ignored.

Can I use timeout with sudo?
Yes. Place sudo before timeout: sudo timeout 60 tcpdump -n -w capture.pcap. If you place timeout before sudo, the timeout process cannot send signals to the privileged command.

Does timeout work with shell built-in commands?
Not directly. timeout runs external commands, while shell built-ins such as cd, read, and ulimit need a shell context. To apply a timeout to a built-in, wrap it with bash -c: timeout 5 bash -c 'read -p "Input: " val'.

How do I timeout a background process?
Use timeout directly: timeout 60 ./long-task.sh &. The timeout process runs in the background and manages the child command. Check its status with wait or jobs.

Troubleshooting #

timeout: command not found
Install GNU coreutils. On most Linux distributions, timeout is included by default, but minimal containers or stripped-down environments may not include it.

Command exits with code 124 unexpectedly
Exit code 124 means the time limit was reached. Increase the timeout value or inspect the command to confirm whether it is hanging.

Process does not stop after timeout
Some processes ignore SIGTERM. Use -k to enforce a kill after a grace period: timeout -k 10 1m COMMAND.

Timeout does not apply to the whole pipeline
Wrap the full pipeline in bash -c, for example: timeout 30 bash -c 'cmd1 | cmd2'.

Conclusion #

The timeout command runs a command with a time limit and terminates it if it exceeds the specified duration. Use -k to forcefully kill processes that ignore SIGTERM, and check exit code 124 in scripts to detect timeouts.

If you have any questions, feel free to leave a comment below.

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 800+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page