timeout コマンド入門 - 実行時間を制限してハングを防ぐ

2026-06-05 読了時間: 約10分 難易度: 初級

この記事で学べること

• timeout で コマンドの実行時間に制限 をかけられるようになる
• 「固まって戻ってこない」コマンドを 自動で打ち切る 方法が分かる
• タイムアウトしたかどうかを 終了ステータス 124 で判定できる
• SIGTERM を無視するしぶといプロセスを -k で強制終了 できる

1. timeout コマンドとは何か?

結論: timeout は「指定した時間を超えたらコマンドを自動で終了させる」コマンド。ハング対策の定番。

timeout 10 コマンド
        ↑   ↑
        |   実行したいコマンド
        制限時間（秒）

2. なぜ timeout が必要なのか?

結論: ネットワーク待ちや無限ループで固まるコマンドを放置すると、スクリプト全体が止まる。timeout がそれを防ぐ。

3. 基本の使い方（時間の指定）

結論: timeout 時間 コマンド の形。数字だけなら秒、s/m/h/d で単位も付けられる。

いちばん基本の形は次の通り。

$ timeout 10 sleep 30

sleep 30 は本来 30 秒待つコマンド。だが timeout 10 を付けると 10 秒で打ち切られる。

時間には単位（サフィックス）を付けられる。

$ timeout 30s コマンド    # 30秒
$ timeout 5m コマンド     # 5分
$ timeout 1h コマンド     # 1時間
$ timeout 2d コマンド     # 2日

4. 終了ステータス 124 でタイムアウトを判定する

結論: timeout で打ち切られたときの終了ステータスは 124。echo $? が 124 ならタイムアウトと判断できる。

timeout が時間切れでコマンドを止めたとき、終了ステータスは 124 になる。これを見れば、タイムアウトしたかどうかを自動で見分けられる。

$ timeout 1 sleep 10
$ echo $?

124

時間内に終わった場合は、コマンド本来のステータスが返る。

$ timeout 10 sleep 1
$ echo $?

0

5. -k でしぶといプロセスを強制終了する

結論: timeout はデフォルトで SIGTERM を送る。無視されるときは -k 時間 で猶予後に SIGKILL を送って確実に止める。

$ timeout -k 5 10 コマンド

これは次の意味になる。

• まず 10 秒 でコマンドに SIGTERM（終了のお願い）を送る
• それでも さらに 5 秒 止まらなければ SIGKILL（強制終了）を送る

timeout -k 5 10 コマンド
         ↑  ↑
         |  本来の制限時間（10秒）→ SIGTERM
         追加の猶予（5秒）→ それでも残れば SIGKILL

6. シグナルを指定する（-s）

結論: -s で送るシグナルを変えられる。終了時にコマンド自身のステータスを返したいなら --preserve-status。

デフォルトでは SIGTERM が送られる。-s（--signal）を使えば、別のシグナルを指定できる。

$ timeout -s SIGINT 10 コマンド

これは Ctrl+C と同じ SIGINT を送る。コマンドによっては、SIGTERM より行儀よく終われることがある。

タイムアウトしたときに 124 へ書き換えず、コマンドが最期に返した値をそのまま受け取りたい ときは --preserve-status を使う。

$ timeout --preserve-status 10 コマンド

7. よくある初心者のつまずき

結論: 時間とコマンドの順番、124 の意味、-k の引数の並びを取り違えやすい。

7-1. 時間とコマンドの順番を逆にする

# NG: コマンドが先になっている
$ timeout sleep 30 10

# OK: 時間 → コマンドの順
$ timeout 10 sleep 30

7-2. 124 を「エラー」と勘違いする

7-3. パイプ全体にかけたつもりで一部しか制限されない

# これは「timeout 10 で grep」だけにかかる書き方ではない
$ timeout 10 grep pattern file | sort

パイプ（|。左のコマンドの結果を、右のコマンドへ渡す書き方）でつないでも、制限がかかるのは timeout 10 grep pattern file の部分だけ。| sort は別扱いになる。

パイプ全体を一括で囲みたいときは、bash -c 'コマンド列'（まとめてひとつのコマンドとして扱わせる書き方）を使う。

$ timeout 10 bash -c 'grep pattern file | sort'

8. ミニ課題：実際にやってみよう

結論: 打ち切り・終了ステータス確認・強制終了の 3 問で timeout を手で確かめる。

課題 1: sleep 30 を 3 秒で打ち切る

やること: 本来 30 秒かかるコマンドを、3 秒で終わらせよう。

$ timeout 3 sleep 30

課題 2: タイムアウトしたか確かめる

やること: 課題 1 のすぐあとに終了ステータスを表示して、124 になることを確かめよう。

$ timeout 3 sleep 30
$ echo $?

課題 3: 止まらないときに強制終了する

やること: sleep 30 を「5 秒で SIGTERM、さらに 2 秒待っても止まらなければ SIGKILL」で止める指定を書こう。

$ timeout -k 2 5 sleep 30

9. コピペ用テンプレート

結論: 基本・単位付き・判定・強制終了・パイプのよく使う型をまとめて手元に置いておく。

# 基本：10秒で打ち切る
timeout 10 コマンド

# 単位を付ける（秒 / 分 / 時）
timeout 30s コマンド
timeout 5m コマンド

# タイムアウト判定（124 ならタイムアウト）
timeout 10 コマンド
echo $?

# 止まらないときは強制終了（10秒 + 猶予5秒で SIGKILL）
timeout -k 5 10 コマンド

# パイプ全体に制限をかける
timeout 10 bash -c 'コマンドA | コマンドB'

# Ctrl+C 相当（SIGINT）で止める
timeout -s SIGINT 10 コマンド

今日の 3 行まとめ

• timeout 時間 コマンド で実行時間に上限を付けられる。順番は 時間が先、コマンドが後
• 終了ステータス 124 はタイムアウトの合図。エラーではなく「予定どおり打ち切った」という意味
• SIGTERM を無視するプロセスには -k 猶予秒 制限秒 で二段構えにする。SIGKILL はいちばん最後の手だて