find Command on Mac: Apple's BSD find Refused 17 of 64

The find command on a Mac is not the one most tutorials assume. Run find --version on this Mac mini (macOS 26.4.1) and you get find: illegal option -- -. There is no version flag. what /usr/bin/find gives the real answer: PROJECT:shell_cmds-329, Apple's fork of FreeBSD's find. The commands you copy from Linux answers are written for GNU find, from GNU findutils. So I took 64 GNU-style find invocations and ran each one through Apple's /usr/bin/find and through GNU find 4.11.0 from Homebrew (gfind), in a fresh copy of the same test tree each time.

Apple's find refused 17 of the 64. Five more ran, exited 0, and returned something different from GNU find. Another five are BSD-only spellings that GNU find refuses, which matters if you write scripts on a Mac and run them on Linux. And on a plain directory walk of 249,362 entries, Apple's find took 2.6 times as long as GNU find.

This is part of my series on the command-line tools macOS bundles. Earlier posts covered tar on Mac, xargs on macOS and stat's "illegal option -- c" error.

The error almost everyone hits first

The first refusal isn't about a GNU extension. GNU find lets you leave out the starting directory and assumes .. BSD find requires at least one path. So the most common Linux one-liner fails on a Mac with an error that names the wrong thing:

$ find -name '*.c'
find: illegal option -- n
usage: find [-H | -L | -P] [-EXdsx] [-f path] path ... [expression]
$ find . -name '*.c'
./src/main.c
./src/lib/util.c

BSD find reads -name as a bundle of single-letter options, gets to n, and gives up. Bare find with no arguments fails the same way, with just the usage line. A Stack Overflow question titled "Illegal option" error when using find on macOS has about 35,000 views, and the top answer is "add a dot". A 2008 question asks how to make find on OS X default to the current directory, and it's still getting views.

Leaving out the path also produces my favorite error in this test. GNU's find -files0-from FILES0 -name '*.c' reads the starting points from a NUL-separated file. Apple's find sees -f, which is a real BSD option meaning "the next argument is a path", takes iles0-from as that path, and reports find: iles0-from: No such file or directory.

The 17 refusals

Every one of these exits 1 with no output. Apple's message is usually find: -printf: unknown primary or operator.

GNU find	Apple's error	What works on a Mac
find -name '*.c', bare find	illegal option -- n / usage	find . -name '*.c'
-printf '%p %s\n' (3 variants)	unknown primary	-exec stat -f '%N %z' {} +
-regextype posix-extended	unknown primary	find -E . -regex ...
-perm /u+x	-perm: /u+x: illegal mode string	-perm +111 (any of the bits)
-executable	unknown primary	-perm +111, which checks mode bits, not access(2)
-readable	unknown primary	-perm -u+r, same caveat
-xtype l (broken symlinks)	unknown primary	find -L . -type l
-fprint OUT	unknown primary	Redirect: > OUT
-used -1	unknown primary	No equivalent
-files0-from FILE	iles0-from: No such file or directory	xargs -0 -J % find % -name '*.c' < FILE
--help, --version	illegal option -- -	man find, what /usr/bin/find
-D tree, -O3	illegal option -- D / O	No equivalent

-printf is the big one. A Stack Overflow question from 2009, "find lacks the option -printf, now what?", has 36,000 views. Apple's stat -f covers most of it, because its format letters are close to -printf's: %N name, %z size, %Sm modification time. They're not the same letters, though, and stat on a Mac has its own GNU differences.

The five that run and do something else

These matter more than the refusals, because a script keeps going.

Command	Apple find	GNU find 4.11.0
-regex '.*\.\(c\|h\)'	0 matches, exit 0	3 matches
-type f,l -name '*link*'	0 matches, exit 0	2 symlinks
-execdir echo {} \;	main.c	./main.c
-ls	Sizes in 512-byte blocks (8)	Sizes in 1K blocks (4)
-ok echo {} \; prompt	"echo ./src/main.c"?	< echo ... ./src/main.c > ?

The regex row is a dialect problem. GNU find defaults to Emacs-style regular expressions, where \| means "or". Apple's find defaults to POSIX basic regular expressions, where it doesn't, so the pattern just never matches. find -E . -regex '.*\.(c|h)' works on a Mac. There's a Unix & Linux question about regex in find on OS X with the same confusion.

The -type f,l row surprised me, so I read the source. In Apple's shell_cmds-329 find, c_type() in function.c runs switch (typestring[0]). It looks at the first character and ignores the rest. -type f,l means -type f, -type lf means -type l, and only a string that starts with an unknown letter, like -type ,, gets an error. GNU's own man page lists the comma form as a "GNU extension" and gives \( -type f -o -type l \) as the portable spelling, which works on both.

The other direction counts too. Apple's find accepts -E, -x, -d, -depth 2 and -perm +111, and GNU find 4.11.0 refuses all five. gfind: invalid file mode '+111' is what a Mac-written script prints on a Linux box. The portable spellings are -xdev for -x and -depth with no number for -d. Both finds also accept -regex without -E, as long as the pattern avoids alternation.

What matched

The 37 that behaved the same are the everyday ones: -name, -iname, -type with one letter, -path/-wholename/-ipath, -mindepth/-maxdepth, -empty, -type d -empty -delete, -newer, -newermt '2024-06-01' and even -newermt '1 day ago', -mtime, -mmin, -size with k/M/c, -perm -u+x, -prune, -not and !, -print0, -exec {} +, -samefile, -lname, -quit, -L and -follow, -xdev, -mount and -fstype. Both also walked the tree in the same order in every case. If your command uses only these, it runs the same on both.

One output difference didn't fit the 64 because it only shows up in a terminal. I made a file whose name contains a newline. Piped, both finds print it raw. At a terminal, GNU find prints ./src/new?line.txt and Apple's prints the newline, so one file looks like two lines. Use -print0 with xargs -0 either way.

Apple's find is slower on a plain walk

I timed a bare listing of /opt/homebrew and /usr/share together, 249,362 entries, five alternating runs each with a warm cache:

/usr/bin/find /opt/homebrew /usr/share > /dev/null   1.152 1.156 1.158 1.167 1.224 s
gfind /opt/homebrew /usr/share > /dev/null           0.431 0.436 0.440 0.444 0.446 s

Medians are 1.158 s and 0.440 s, so GNU find is about 2.6 times faster here. -type f and -name '*.h' showed the same gap: about 1.2 s against 0.43 to 0.48 s, with identical counts (174,465 files, 8,014 headers). Apple's binary is native arm64e, so this isn't Rosetta. I didn't trace where the time goes. For most interactive searches a second doesn't matter. In a loop it adds up. If you're searching by name across a whole disk, mdfind uses the Spotlight index instead, but on my tests it missed 8 of 21 files.

What I'd do

Write find . with an explicit path every time. It costs one character and works on both. For anything with -printf, -regextype, -xtype or a comma in -type, install GNU findutils and call it by name:

brew install findutils
gfind --version          # find (GNU findutils) 4.11.0
# only if a Linux script must find it as "find":
export PATH="$(brew --prefix)/opt/findutils/libexec/gnubin:$PATH"

The same formula installs gxargs and glocate. I'd put the gnubin line in the script that needs it rather than in ~/.zshrc, because other tools on a Mac sometimes call find and expect Apple's options, like -E or -x. Findutils 4.11.0 came out on 2026-07-11, according to the GNU download directory. The full option reference is the GNU find manual. For the BSD side, Apple's man find is dated December 22, 2023 and closely follows FreeBSD's find(1).

FAQ

Why does find say "illegal option -- n" on Mac?

macOS uses BSD find, which requires a starting directory before the expression. GNU find on Linux assumes the current directory if you leave it out. On a Mac, find -name '*.c' fails because BSD find reads -name as single-letter options. Add the path: find . -name '*.c'.

Does find on Mac support -printf?

No. Apple's find exits 1 with "unknown primary or operator". Either pipe the matches to stat, for example find . -type f -exec stat -f '%N %z' {} +, or install GNU findutils with brew install findutils and use gfind, which supports -printf.

How do I use GNU find on a Mac?

Run brew install findutils. Homebrew installs GNU find as gfind, so it doesn't replace /usr/bin/find. If a script has to call it as find, put $(brew --prefix)/opt/findutils/libexec/gnubin at the front of PATH inside that script. The formula also provides gxargs and glocate.

Update, October 12, 2026: du is the next tool in this series. I ran 62 GNU-style du commands on the same Mac, and Apple's du refused 27, including --max-depth and --exclude, and printed a different number for 7 more. The results are in the du command on Mac.

How this was checked: 64 find invocations, each run in a fresh copy of a 23-entry test tree in /tmp (files with a space, a newline, a hidden directory, an empty file and directory, a working and a broken symlink, set mtimes), on 2026-10-12 on a Mac mini with macOS 26.4.1 (25E253). For each I recorded the exit code, the first stderr line and the sorted output of Apple's /usr/bin/find (shell_cmds-329) and Homebrew's GNU findutils 4.11.0 gfind, which was already installed on this machine. The -type behavior was confirmed in Apple's published source for shell_cmds-329. Timings are wall-clock from five alternating warm runs. Stack Exchange threads were read through the Stack Exchange API. The probe scripts and raw results are in my research notes for this post.