timeout Command Not Found on Mac: 19 of 109 Are Missing

On August 15, two parallel steps in this site’s publishing pipeline died in the same run with the same one-line error: zsh: command not found: timeout. Nothing timed out. Nothing even started. I had prefixed two long-running commands with timeout 180 the way you would on Linux, and on a Mac that prefix kills the command before execution: the wrapper binary does not exist, so the wrapped work never runs. The failure is not slowness. It is syntax.

Today I reproduced it on stock macOS 26.4.1 (build 25E253), then went one step further: I checked every program GNU coreutils can build, all 109 of them, against a clean system PATH. The result explains why this one missing command causes so much confusion, and which of the three fixes holds up.

The failure is exit 127, not a timeout

$ zsh -c 'timeout 180 echo hi'
zsh:1: command not found: timeout    # exit 127
$ bash -c 'timeout 180 echo hi'
bash: timeout: command not found     # exit 127

Both stock shells (zsh 5.9, bash 3.2.57) return 127. Hold on to that number. Per the GNU coreutils manual, timeout itself reserves an exit-code ladder: 124 when the command times out, 125 when timeout itself fails, 126 when the command is found but cannot run, and 127 when the command cannot be found. So exit 127 in a script means either your machine has no timeout, or it has one and your actual command is missing. Two different failures, one exit code; only the log line tells them apart.

The BSD excuse is ten years stale

The standard explanation says macOS ships a BSD userland and timeout is a GNU tool. Half right. The FreeBSD manual page is explicit in its HISTORY section: the timeout command first appeared in FreeBSD 10.3, released in 2016, and the same page notes the GNU version appeared in coreutils 7.0 back in 2008. FreeBSD has shipped it for a decade. macOS inherited its userland from BSD and then mostly stopped syncing; as of 26.4.1 there is still no /usr/bin/timeout. This is not a GNU-versus-BSD split. Both lineages adopted the tool. macOS did not.

All 109 coreutils programs against a stock Mac

To see how typical this absence is, I took the program list from the coreutils source README (109 names) and probed each with command -v, PATH pinned to /usr/bin:/bin:/usr/sbin:/sbin so Homebrew could not leak in. Stock macOS 26.4.1 has 90 of the 109. The 19 missing programs sort into five groups:

Group	Programs	Stock replacement
SELinux-only	chcon, runcon	Not applicable on macOS
GNU aliases	dir, vdir, dircolors, coreutils	ls variants; no multicall binary
Substitute exists	tac, shuf, nproc	tail -r, sort -R or jot, sysctl -n hw.ncpu
Niche, no substitute	b2sum, base32, basenc, factor, hostid, numfmt, pinky, ptx, shred	None (rm -P is a documented no-op)
Common, no substitute	timeout	None

I verified the substitutes in the third row today, and one carries a trap: BSD sort -R is not shuf. It randomizes by hashing the sort key, so identical lines travel together; I ran it twice on a five-line file with duplicates and both runs kept the duplicate pairs adjacent. The closest thing to shred is dead on arrival too: the macOS rm man page documents -P as a flag that has no effect, kept for 4.4BSD-Lite2 compatibility.

Now look at the pattern. Two SELinux programs that mean nothing on a Mac. Four GNU spellings of what ls already does. Three that are one rename away. Nine that most scripts never invoke. timeout is the only program on the list that is both routinely used in scripts and has no stock replacement. That intersection is why the search traffic for missing coreutils funnels into this single name. It is also the second entry in what is turning into a BSD-gap series on this blog: flock is missing too, and the stock replacement for it is covered in macOS flock alternative.

What a missing timeout breaks: gates that fail open

Exit 127 has a habit of being swallowed. Three public exhibits, each confirmed against the original thread today:

• vishnubob/wait-for-it #108, open since 2021: right after timeout: command not found, the script prints that a timeout occurred after waiting 10 seconds. The wrapper misreports a missing binary as a real timeout.
• obra/double-shot-latte #18, March 2026: a Claude Code judge hook calls timeout, gets exit 127, and an error handler catches it and falls through to "decision": "approve". In the reporter’s words, the hook never actually judges anything on macOS. A gate that fails open is worse than no gate, and it is the same silence I documented in Claude Code hooks not working.
• NVIDIA/NemoClaw #2160, April 2026, closed: e2e test scripts wrapped their whole run in timeout in the preamble and crashed on any clean Mac, until the suite standardized its handling.

My August 15 incident is the same shape as the failures in cron jobs failing silently: the error was real, printed once, and scrolled away while the run reported nothing useful.

Three fixes, measured

1. Homebrew coreutils. brew install coreutils installs GNU timeout as gtimeout, g-prefixed so it does not clobber the BSD tools. The formula is at 9.11 and shows 69,623 installs in the past 30 days in Homebrew’s public analytics, which is a measure of how routinely people patch this gap. If you want the unprefixed names, the formula ships a gnubin directory to prepend to PATH. The catch is fleet-wide: every machine and every CI runner needs the install, or you are back at exit 127.

2. The stock-Perl one-liner. macOS 26 still ships /usr/bin/perl (5.34.1 on this machine), and Perl’s alarm gives you a dependency-free timeout:

perl -e 'alarm shift; exec @ARGV' 180 long-command --flags

I measured it against sleep 30 with a 2-second alarm: killed on schedule, exit 142, which is 128 plus SIGALRM’s 14. Two caveats from the same session. First, 142 is not GNU’s 124, so downstream checks written for real timeout will misread it. Second, alarm signals only the process you exec’d, not its children: when I wrapped sh -c 'sleep 30; echo done', the sh died at 2 seconds and its sleep child survived the full 30. Right for a single binary, wrong for anything that forks.

3. Move the timeout up a layer. This is what I actually did after August 15. The runner that executes my pipeline commands accepts a per-command timeout enforced by the parent process, so the shell never needs a timeout binary and the fix cannot rot machine by machine. The same logic applies in CI: a step-level timeout setting beats a shell prefix. If you must keep a portable shell wrapper, detect and fail closed instead of open:

T="$(command -v timeout || command -v gtimeout)" || {
  echo "no timeout binary; refusing to run unbounded" >&2
  exit 1
}
"$T" 180 long-command --flags

One last trap: checking with man timeout on a stock Mac appears to succeed. It opens curs_inopts(3X), the ncurses C function named timeout. If you use the man page as an existence check, you get a false positive from a different timeout that has nothing to do with your shell.

FAQ

Does macOS have a built-in timeout command?

No. As of macOS 26.4.1 there is no /usr/bin/timeout, and running timeout in zsh or bash exits 127 with command not found. FreeBSD added the tool in 10.3 (2016) and GNU coreutils in 7.0 (2008); macOS adopted neither.

What is gtimeout on a Mac?

gtimeout is GNU timeout as installed by Homebrew’s coreutils formula. Homebrew prefixes the GNU tools with g so they do not shadow the BSD tools macOS ships; prepend the formula’s gnubin directory to PATH if you want to call it as plain timeout.

How do I get a timeout on macOS without installing anything?

Use the bundled Perl: perl -e 'alarm shift; exec @ARGV' 180 your-command. It kills the command after 180 seconds with exit code 142 (128 plus SIGALRM). It signals only the exec’d process, not its children, so it suits single binaries rather than pipelines that fork.

Method and sources: every measurement above ran on 2026-08-28 on this site’s production Mac mini, stock macOS 26.4.1 (25E253), with PATH pinned to the four system directories; the 109-program list comes from the GNU coreutils source README, and the presence sweep, the perl alarm runs, the sort -R runs, and the exit codes are quoted from that session. The three GitHub issues were read in full via the GitHub API the same morning. The August 15 incident is from this site’s ops notes, written the day it happened.