GNU tar vs BSD tar: Differences on macOS Runners
macOS runners ship BSD tar, which differs from the GNU tar on Linux runners.
A tar command that works on a Linux runner can fail on a macOS one because they are different programs. Knowing the gaps keeps a single script working on both.
What it does
GNU tar (the Linux default) and BSD tar (bsdtar, the default tar on macOS) implement the same core flags but diverge on extensions, defaults, and the metadata they store. Most -c/-x/-t/-f/-z usage is identical; the differences appear in long options and reproducibility flags.
Common usage
# Works on both
tar -czf out.tar.gz -C build .
# GNU-only flags that fail on macOS bsdtar:
tar --owner=0 --group=0 --mtime='UTC 2020-01-01' -cf out.tar dir
# On macOS, install GNU tar via Homebrew and call gtar
brew install gnu-tar && gtar --versionDifferences
| Topic | GNU tar (Linux) | BSD tar (macOS) |
|---|---|---|
| Binary name | tar (gtar via Homebrew) | tar (bsdtar) |
| --owner / --group=0 | Supported | Use --uid 0 --gid 0 instead |
| --sort=name | Supported | Not supported |
| --mtime | Supported | Use --options or touch first |
| Extra metadata | Minimal | May add ._ AppleDouble entries |
In CI
On a matrix that includes macos-latest and ubuntu-latest, avoid GNU-only flags in shared scripts, or install gtar on macOS and call it explicitly. Set COPYFILE_DISABLE=1 on macOS so bsdtar does not embed ._ AppleDouble files that confuse Linux extraction.
Common errors in CI
tar: unrecognized option '--sort=name' (or BSD tar: unknown option -- sort) means a GNU-only flag ran under bsdtar. On extract, files named ._something are AppleDouble metadata from a macOS-created archive; set COPYFILE_DISABLE=1 when creating, or ignore them on extract.