macOS rsync Version Is openrsync: 42 Flags Rejected

On this site’s production Mac mini, asking for the rsync version gets you two lines that disagree with each other:

$ /usr/bin/rsync --version
openrsync: protocol version 29
rsync version 2.6.9 compatible

The first line is the truth. The second is a compatibility string, and it is the reason a lot of people conclude their Mac is running a nineteen-year-old rsync and stop investigating. It is not. On macOS 26.4.1 (build 25E253) /usr/bin/rsync is openrsync, a clean-room reimplementation Apple ships under the ISC license so it never has to touch rsync 3.x’s GPLv3. codesign -dv puts Identifier=com.apple.rsync on it, man rsync renders a page titled OPENRSYNC(1), and strings finds Apple-only symbols in it (apple_open_xattrs, apple_flist_sent) that exist in no upstream rsync.

So the useful question is not what version it claims. It is: which of the flags in your script still work? I probed all of them and counted.

145 options probed, 42 rejected

I took the OPTION SUMMARY block of the official rsync man page — it self-identifies as current for rsync 3.5.1 — and parsed 151 long options out of it. Then I ran each one against this machine’s binary as a dry run into a throwaway directory pair, and classified by stderr: unrecognized option or invalid option means rejected, anything else (including option requires an argument) means the parser knows it. Six were skipped because they short-circuit or start a daemon: --help --version --daemon --config --dparam --no-detach.

Of the 145 actually probed, 103 are recognized and 42 are rejected.

The 42, grouped by what they were for:

Group	Rejected on macOS 26.4.1
Metadata (10)	--acls --xattrs --atimes --crtimes --omit-link-times --open-noatime --fake-super --chown --usermap --groupmap
Output and logging (4)	--info --debug --stderr --outbuf
Transfer and performance (12)	--append-verify --preallocate --copy-devices --write-devices --checksum-choice --compress-choice --compress-threads --skip-compress --max-alloc --fsync --inc-recursive --no-inc-recursive
Path and safety (6)	--mkpath --munge-links --insecure-links --delete-missing-args --ignore-missing-args --confine-root
Remote and argument handling (8)	--remote-option --secluded-args --old-args --old-dirs --copy-as --early-input --trust-sender --iconv
Time limits (2)	--stop-after --stop-at

Short forms match: -A and -X both come back as invalid option. In their place openrsync has -E/--extended-attributes, which is Apple’s own and appears nowhere in rsync 3.5.1. Remember that flag — it sets the trap at the end of this post.

The three flags people actually search for

Google’s autocomplete for rsync unknown option offers, in order, --append-verify, --mkpath and --chown. All three are in the rejected list, which is a tidy confirmation that this census is describing a real population of broken scripts rather than a curiosity.

--mkpath is the interesting one, because it is rejected for a reason nobody warns you about: openrsync already behaves as though it is always on. Measured here, with no deep/ directory existing beforehand:

$ /usr/bin/rsync -a src/ deep/a/b/c/ ; echo $?
0
$ ls -R deep
a       b       c

Samba rsync documents the opposite default, and says why: “If any other component does not exist that is an error, as this can help to catch mistakes in the destination path specification.” That guard is gone on macOS. A typo in a destination path does not fail loudly any more — it quietly builds the typo as a directory tree and reports success. If you have a script whose safety relies on rsync refusing a bad destination, it does not have that safety on a Mac.

Your shell suggests flags your rsync rejects

macOS ships a zsh completion for rsync at /usr/share/zsh/5.9/functions/_rsync. I parsed the long options out of it: 178, of which 31 are in the rejected-42 list. Another 103 are flags the binary does take; the remaining 44 I did not probe, being daemon options or patch-set flags outside rsync 3.5.1’s own summary. So on a stock Mac, pressing Tab after rsync -- will happily offer you --info, --mkpath, --xattrs and --chown, and the binary sitting next to that completion file will refuse every one. Two components of the same OS release disagree about what the tool can do.

The documented exit codes are wrong

The EXIT STATUS section of man rsync on this machine says the tool “exits 0 on success, 1 if an error occurs, or 2 if the remote protocol version is older than the local protocol version.” Three values. Here is what it actually returned:

Situation	Exit code
Source directory does not exist	23
One unreadable file, the rest copied	23
Unrecognized option	1
Remote host unreachable over ssh	255
Dry run into a destination whose parent is missing	0

23 is samba rsync’s partial transfer due to error, and the openrsync man page never mentions it. 255 is ssh’s own connection-failure code passed straight through. If your error handling branches on the documented set, it will mis-handle the two cases you are most likely to hit. I measured these as cmd >/dev/null 2>&1; echo $? for a reason — putting a pipe after the command hands you the exit code of the last stage instead, which is how you end up believing a failing command succeeded.

One more: forcing a newer protocol is a warning, not an error. --protocol=31 prints warning: --protocol=31: is not supported by this version of openrsync. min: 27, max: 40 — twice — and then runs anyway and exits 0. Values 27, 28 and 29 are accepted silently; 30 and up warn. The advertised ceiling of 40 is not reachable.

The workaround you will find on the web is dead

macOS 15.0 through 15.3 shipped both implementations behind a switch. You could set CHOSEN_RSYNC=rsync_samba, or point a /var/select/rsync symlink at it, and get the old binary back. That advice is still the top result in a lot of places. On 26.4.1 it does nothing:

$ CHOSEN_RSYNC=rsync_samba /usr/bin/rsync -V
openrsync: protocol version 29

$ ls -la /var/select/
sh -> /bin/bash          # no rsync entry

$ man rsync | grep -c CHOSEN_RSYNC
0

The /var/select mechanism itself is alive — it still picks your sh — but rsync is no longer one of its clients, and no rsync_samba binary exists anywhere under /usr, /bin or /sbin. An accepted Apple StackExchange answer (479297) preserves the old man page text and appends the correction, and the May 2026 Hacker News thread on openrsync pins it down the same way: samba rsync was removed in 15.4, not 15.0. That distinction matters if you are reading a 2024 blog post and wondering why the trick does not work.

The reverse trap: do not put Homebrew rsync first

The standard advice is to install real rsync from Homebrew and move on. That works, and if you need --xattrs or --info=progress2 there is no alternative. But putting it ahead of /usr/bin in your global PATH has a cost that is easy to miss, reported in the 464-comment Hacker News thread on the switch: xcodebuild shells out to rsync when assembling an .ipa, and it passes --extended-attributes — the Apple-only flag from earlier. Homebrew rsync does not know that flag, so the iOS build fails with an error that has nothing to do with rsync on its face.

The flags point in both directions. That is why on this machine scripts call an absolute path rather than bare rsync, the same rule we landed on after timeout turned out not to exist on macOS at all and after flock needed a different binary name here. A bare command name is a bet that every machine in your fleet resolves it the same way, and macOS keeps losing that bet in new ways.

A caveat that makes this post expire

Apple is closing the gap, so a census like this is only true for one build. Two flag complaints from the 2025 threads no longer reproduce on 26.4.1: the duplicated deletion lines under --delete --dry-run now print exactly two lines for two files, and --log-file and --log-file-format, which broke someone’s backup script badly enough that they reinstalled from Homebrew, both work here. Re-run the probe on your own build before trusting the 42. It is one loop over a list of flags with -n and a throwaway directory; 145 probes took 0.3 seconds here.

Method and sources: every measurement above was taken on 2026-09-24 on this site’s Mac mini (Mac16,10, macOS 26.4.1 build 25E253), against stock /usr/bin/rsync with no Homebrew rsync installed. The 151-option source list was parsed from the rsync project’s own man page fetched the same day, which states it is current for 3.5.1; the probe classified each flag by the binary’s stderr, and the raw census, the 42 rejected and the 103 recognized are kept in this repo’s research notes. The zsh completion count comes from the file macOS ships at /usr/share/zsh/5.9/functions/_rsync. The community reports were pulled in full through the Hacker News Algolia items API and the StackExchange API rather than read from search snippets, and the two 2025 bug reports were retested here before being described as fixed.