Update Bash on Mac: 3.2.57 Failed 28 of 28, 16 Silently

The bash on a Mac is version 3.2.57. On this Mac mini, running macOS 26.4.1, /bin/bash --version prints GNU bash, version 3.2.57(1)-release (arm64-apple-darwin25). The binary is dated April 6, 2026, so Apple still rebuilds it, but the source never moves forward: the newest tag in Apple's open-source bash repository is bash-144, and it still holds a bash-3.2 directory whose COPYING file is GPL version 2. Homebrew's current bash is 5.3.20, licensed GPL-3.0-or-later. Apple has never said in public that the license is why it stopped at 3.2. What it did do was make zsh the default shell starting with macOS 10.15 and leave bash frozen.

That would be a trivia question if scripts didn't assume a newer bash. Most do. Anything written on Linux in the last fifteen years can use associative arrays, mapfile or ${var,,}, and all of those are bash 4.0 or later. So before covering how to update bash on a Mac, I measured what happens when a modern script hits 3.2.

28 bash 4 and 5 features, run through 3.2.57

I wrote 28 probes. Each is a one-line script with an expected output, and each feature comes from the bash NEWS file for 4.0 through 5.3. I ran every probe under /bin/bash and under Homebrew's bash 5.3.20, with a clean environment and LC_ALL=en_US.UTF-8. A probe passed only when both stdout and the exit code matched. Ten control probes using features 3.2 already has ([[ =~ ]], printf -v, pipefail, process substitution and so on) passed 10 of 10 on both shells, so the harness wasn't the problem.

Bash 5.3 passed all 28. Bash 3.2.57 passed none. The part that matters is how it failed. 12 probes stopped with a nonzero exit code. The other 16 ran to the end and exited 0 with the wrong output, and 6 of those 16 printed nothing at all to stderr.

Feature (since)	bash 3.2.57 on macOS
declare -A (4.0)	exit 0, printed 2 instead of 1, usage error on stderr
mapfile / readarray (4.0)	exit 0, array length 0, "command not found"
shopt -s globstar (4.0)	exit 0, printed the literal **/*.txt
{1..9..4} step (4.0)	exit 0, printed {1..9..4}, no stderr
{01..03} padding (4.0)	exit 0, printed 1 2 3, no stderr
$BASHPID (4.0), $EPOCHSECONDS (5.0), $SRANDOM (5.1)	exit 0, all three empty, no stderr
$'é' (4.2)	exit 0, printed the literal é, no stderr
read -t 0.2 (4.0)	exit 0, read returned 1 ("invalid timeout specification")
shopt -s lastpipe (4.2)	exit 0, variable stayed empty
declare -n (4.3), ${a[-1]} (4.3), wait -n (4.3), declare -l (4.0), coproc (4.0)	exit 0, wrong or empty output, error on stderr
${v,,}, ${v^^} (4.0), ${v@Q} (4.4), ${ cmd; } (5.3)	exit 1, "bad substitution"
|&, &>>, ;;& (4.0), [[ -v x ]] (4.2)	exit 2, syntax error before anything runs
exec {fd}>file (4.1)	exit 127, "exec: {fd}: not found"
printf '%(%Y)T' (4.2)	exit 1, "invalid format character"
set -u with empty "${a[@]}" (fixed in 4.4)	exit 127, "a[@]: unbound variable"
wait -n -p var (5.1)	exit 1, "wait: -n: invalid option"

The associative array result is the one I'd worry about most. declare -A m fails, the script keeps going, and m[foo]=1; m[bar]=2 turns into a plain indexed array. Bash evaluates foo and bar as arithmetic, both unset names come out as 0, and both writes land in m[0]. So echo "${m[foo]}" prints 2. Every key reads back the last value written, and the script exits 0. The usage message does go to stderr, but under cron or launchd nobody reads stderr.

The six fully quiet failures are smaller, but nothing tells you about them. A backup script that names files {01..12} gets 1 to 12 and sorts wrong. A log line stamped with $EPOCHSECONDS gets an empty field. Brace expansion with a step isn't an error in 3.2 because the 3.0 NEWS entry for sequence expressions says it plainly: "the increment is always 1". Anything else isn't a sequence, so bash leaves the text alone.

The GitHub reports are mostly from 2026

To see whether this still hurts people, I pulled every GitHub issue and pull request that contains the exact error strings. The search was in:title,body,comments and none of the result sets came back incomplete.

• "declare: -A: invalid option": 940 results from 766 repositories. 559 of them (59%) were created in 2026.
• "mapfile: command not found": 1,003 results (the API returns at most 1,000) from 774 repositories. 910 of the 1,000 were created in 2026.
• "globstar: invalid shell option name": 114, with 39 from 2026. "wait: -n: invalid option": 68, with 39 from 2026. "declare: -n: invalid option": 45, with 30 from 2026.

GitHub itself got busier in 2026, so the raw counts overstate this. I ran the same yearly counts on two control strings. A generic bash error, "syntax error near unexpected token", went from 1,519 in 2025 to 6,150 so far in 2026, which is 4.0 times as many. The macOS sed error I covered in sed invalid command code grew 5.3 times. declare -A grew 5.9 times, about the same as the sed error. mapfile grew 24.6 times (37 to 910), and that one stands out.

I can't prove why from search results. One thing I can count: 342 of the 910 mapfile reports from 2026, and 183 of the 559 declare -A reports, contain a coding-agent marker in the body, such as "Generated with Claude Code", a "Co-Authored-By: Claude" line, or the words Codex or Copilot. That's a lower bound on agent involvement. It doesn't show that the agent wrote the bad line. The reports themselves read the same way. A beads issue describes the main branch's macOS test leg going red because a new script used mapfile under Apple bash 3.2. asn #108 is titled "macOS ships Bash 3.2 - asn fails with declare -A unless using newer Bash". In agent-crew #186, a privacy-scan hook that used declare -A had been failing on every run without saying anything. And an open Helix pull request rewrites the editor's bash completion to support 3.2 rather than ask Mac users to upgrade.

How to update bash on a Mac, and the part that doesn't update

Installing bash 5 takes one command and doesn't touch /bin/bash:

brew install bash
/opt/homebrew/bin/bash --version   # GNU bash, version 5.3.20(1)-release

On this machine the bottle poured in 3 seconds and takes 13 MB. In a shell set up with brew shellenv, /opt/homebrew/bin comes before /bin, so typing bash now gets 5.3. Scripts don't all follow PATH, though. With bash 5.3 first on PATH, I ran the same one-line script three ways:

#!/bin/bash          -> 3.2.57(1)-release
#!/usr/bin/env bash  -> 5.3.20(1)-release
sh script.sh         -> 3.2.57(1)-release   (/bin/sh is bash 3.2 in sh mode)

A #!/bin/bash shebang names an absolute path, so installing a newer bash changes nothing for that script. You either change the shebang to #!/usr/bin/env bash or run the script as /opt/homebrew/bin/bash script.sh. The env route has its own catch. Jobs started by launchd don't get your shell's PATH, and launchd's default PATH has no /opt/homebrew/bin (I measured that in launchd plist environment variables). Under launchd, env bash quietly finds /bin/bash 3.2 again. For scheduled jobs, set PATH in the plist or call the Homebrew path directly.

To make bash 5 your login shell, add it to /etc/shells and then run chsh:

echo /opt/homebrew/bin/bash | sudo tee -a /etc/shells
chsh -s /opt/homebrew/bin/bash

I didn't run those two lines on this Mac. Its login shell is zsh, it's a headless machine I reach over SSH, and changing the shell there isn't my decision to make. Right now /etc/shells lists only the system shells, /bin/bash included.

If a script has to run on Macs you don't control, make it fail loudly instead of silently. These lines exit 1 with a message on 3.2.57 and pass on 5.3:

if ((BASH_VERSINFO[0] < 4)); then
  echo "needs bash 4+, got $BASH_VERSION" >&2; exit 1
fi

Or stay inside 3.2. Both of these ran correctly on /bin/bash. They replace mapfile and fix the empty-array set -u error:

a=(); while IFS= read -r l; do a+=("$l"); done < <(printf 'x\ny\n')
set -u; b=(); for i in ${b[@]+"${b[@]}"}; do :; done

This is the same pattern as the other tools Apple ships. GNU Make on the Mac is 3.81 and awk on the Mac is a 2020 snapshot. In both, most failures exit 0. Exit codes in pipelines have their own trap, covered in bash pipe exit code.

FAQ

What version of bash comes with macOS?

macOS 26.4.1 ships GNU bash 3.2.57 at /bin/bash, and /bin/sh is the same bash running in sh mode. Apple's open-source bash-144 tree is still bash 3.2 under GPL version 2, while the current upstream release is bash 5.3. The default login shell has been zsh since macOS 10.15 Catalina.

How do I update bash on a Mac?

Run brew install bash, which installs bash 5.3 at /opt/homebrew/bin/bash and leaves /bin/bash alone. Scripts that start with #!/bin/bash still run 3.2, so change their shebang to #!/usr/bin/env bash or call /opt/homebrew/bin/bash directly. To use bash 5 as your login shell, add /opt/homebrew/bin/bash to /etc/shells with sudo and run chsh -s /opt/homebrew/bin/bash.

Why does declare -A say invalid option on Mac?

Associative arrays arrived in bash 4.0, and macOS still ships bash 3.2.57, so declare -A prints "declare: -A: invalid option". The script keeps running, and later assignments like m[foo]=1 silently become indexed-array writes to m[0], so every key returns the last value. Run the script with Homebrew's bash 5, or add a BASH_VERSINFO check that exits on bash 3.

Method: I ran 28 feature probes and 10 control probes (research/update-bash-mac-raw/probes.py, with each expected output in the file) through /bin/bash 3.2.57 and Homebrew bash 5.3.20 on a Mac mini M4 (Mac16,10) running macOS 26.4.1 on October 11, 2026. Each probe ran as bash -c with PATH=/usr/bin:/bin and LC_ALL=en_US.UTF-8, and passed only if stdout and exit code both matched. The "since" versions come from the bash NEWS and CHANGES files on Chet Ramey's site. The GitHub figures are exact-phrase issue and PR searches (in:title,body,comments) run the same day. All results were fetched for the five error strings. The yearly counts use created: date ranges, so 2026 is a partial year. A mention of an error string is not a confirmed macOS bug, and the agent-marker count is a keyword match on issue bodies, not a judgment about who wrote the code. Homebrew bash was unlinked during the probes so it couldn't shadow /bin/bash for other jobs on this Mac, and I removed it afterwards.