timeout-dead

Lightweight command timeout utility with zero runtime dependencies. Runs any shell command with a configurable time limit and termination signal. If the command exceeds the timeout, timeout-dead sends the chosen signal, waits a 1-second grace period, then force-kills the process. Fully cross-platform — Linux, macOS, and Windows (Git Bash / WSL).

Installation

pip install timeout-dead

Or via uv:

uv tool install timeout-dead

Requires Python 3.10 or later. Zero runtime dependencies — pure Python standard library.

Quick start

# Run a command with default 60s timeout
timeout-dead "python -c 'print(42)'"

# Short alias also works
time-d "echo hello"

# Specify a custom timeout
timeout-dead --sec 120 "npm run build"

# Sub-second timeouts work too
timeout-dead --sec 0.5 "potentially-hanging-tool"

# Use SIGINT instead of default SIGTERM
timeout-dead --signal INT --sec 30 "long-running-server"

# Run silently — suppress all normal output
timeout-dead --no-output "curl -s https://example.com"

# Capture stderr/stdout and print them in separated blocks
timeout-dead --capture-output "git diff --stat"

Usage

usage: timeout-dead [-h] [-v] [--sec SECONDS] [--signal SIGNAL] [--no-output]
                    [-c] COMMAND ...

Lightweight command timeout utility.

positional arguments:
  COMMAND               command to execute

options:
  -h, --help            show this help message and exit
  -v, --version         show version and exit
  --sec SECONDS         timeout in seconds (default: 60.0, accepts floats)
  --signal SIGNAL       signal to send on timeout (TERM, KILL, HUP, INT)
  --no-output           suppress normal output and override --capture-output
  -c, --capture-output  capture and format stdout/stderr with separators

Flag priority:

1. -h / --help and -v / --version exit immediately and ignore all other arguments.
2. --sec and --signal apply whenever a command is executed.
3. --no-output suppresses all normal output and has priority over --capture-output.
4. --capture-output is enabled only when --no-output is not set.
5. COMMAND is required unless -h / --help or -v / --version is used.

How it works

1. timeout-dead starts the command in a new process group (Unix) / console group (Windows).
2. A background timer waits for the specified timeout.
3. If the command finishes in time, its output and exit code are forwarded.
4. If the timeout expires:
   • The chosen signal is sent to the process group.
   • After 1 second, if the process is still running, SIGKILL (Unix) or process.kill() (Windows) is sent.
   • A Timeout exceeded message is printed to stderr.

Windows signal note: On Windows, CTRL_BREAK_EVENT (used for TERM and HUP) is sent to the main process only — child processes may not receive it. They will be force-killed after the 1-second grace period. For critical cleanup, use KILL or ensure the parent handles cleanup.

Process group note: Processes that explicitly detach from their process group (e.g., via setsid or nohup) may not be terminated. Even KILL may not reach processes that have created a new session.

Cross-platform

Zero code changes between platforms. timeout-dead detects the OS at startup and uses the native termination strategy:

Tested on all three platforms in CI.

Signal reference

Why subprocess timeout is not enough

Python's built-in subprocess timeout only kills the direct child, not its entire process tree. If your command spawns subprocesses (npm install, make, docker build), children survive the parent kill.

timeout-dead uses process groups to terminate everything — every subprocess, pipeline, and child.

Real-world scenarios

For AI agents

If you build agents that execute shell commands, timeout-dead is essential infrastructure. Agents frequently generate commands that hang — waiting for input, entering infinite loops, or starting interactive programs.

Instead of agents freezing indefinitely, wrap every command:

timeout-dead --sec <timeout> --signal <signal> "<command>"

No dependencies, no code changes. Agent always gets a response — exit code + output — and can implement retry, fallback, or user notification.

Development

git clone https://github.com/UmbrellaLeaf5/timeout-dead
cd timeout-dead
uv sync --extra dev
uv run pytest tests/ -v
uv run ruff check src/timeout_dead/ tests/
uv run ruff format --check .
uv run pyright src/timeout_dead/

License

Unlicense — public domain.

Timeout icons created by pocike - Flaticon