Writing a portable POSIX sh script across Linux, BSD, macOS and AIX

What it is

POSIX.1-2017 defines the Shell Command Language independently of any one implementation. /bin/sh on a given system might be dash (Debian/Ubuntu's default, whose manual page describes it as a POSIX-compliant command interpreter), bash in POSIX mode (RHEL-family Linux, macOS), ksh (AIX), or another shell entirely — a script that only ever ran against bash's extensions can fail the moment /bin/sh points somewhere else.

Why it matters

Two separate portability problems show up:

• Shell syntax: bashisms — [[ ]], arrays, function name() {}, source, <(...) process substitution, set -o pipefail and $'...' (the last two only entered POSIX in the 2024 edition; dash 0.5.12 supports neither) — are not in POSIX.1-2017 sh, and dash rejects or silently mishandles many of them. local is not POSIX either but dash accepts it. Debian's checkbashisms tool, described in its manual page as a script to "check for bashisms in /bin/sh scripts", is built for exactly this: run it over any script that declares #!/bin/sh.
• Command flags differ by vendor: the shell can be portable while the external tools it calls are not. sed -i needs a mandatory extension argument on FreeBSD/macOS's BSD sed (documented as editing "files in-place similarly to" -I, taking an extension even if empty) but takes an optional, directly-attached suffix on GNU sed — sed -i '' -e ... is required on the BSD side and wrong on GNU's (GNU treats '' as a file name and exits 2). sed -i.bak -e ... file && rm file.bak works on both. readlink -f is defined the same way (following every symlink to produce a canonical path) in GNU coreutils and in FreeBSD's manual, and macOS has it only since 12.3; it is missing on older macOS and on many non-GNU/non-BSD platforms (for example AIX) without installing coreutils. date (GNU date -d, BSD date -j -f/-v), stat (GNU stat -c, BSD stat -f) and find diverge similarly between GNU and BSD-derived userlands.

How to apply

• Declare the shell honestly: use #!/bin/sh only for scripts that pass checkbashisms cleanly; use #!/bin/bash and accept the portability cost when bash features are genuinely needed.
• Avoid GNU-only flags in portable scripts, or branch on uname -s/tool --version output and call the vendor-specific form (sed -i '' ... on Darwin/FreeBSD, sed -i ... on Linux).
• Prefer flags defined by POSIX itself (sed -e, printf over echo -e, command -v over which) when a script must run unmodified on the widest set of /bin/sh implementations, including AIX's shell.
• Test the actual /bin/sh on each target, not just bash in POSIX mode; GNU Bash's own "Bash POSIX Mode" changes many defaults but is not identical to dash or ksh behaviour.

Pitfalls

• Assuming bash --posix or a #!/bin/sh shebang on a system where /bin/sh is actually bash proves POSIX compliance; running under dash as well catches far more, though no single shell proves it.
• Hardcoding sed -i with a single form and shipping the script to both a Linux CI runner and a macOS developer machine.
• Relying on readlink -f on a platform where it is not installed, without a fallback such as (cd "$(dirname -- "$f")" && pwd -P), which canonicalizes only the directory part, not a symlink in the last component.