Six tools, one disk,
four different questions.

1 · Mental model

There is no such thing as "searching your Mac." There are two independent choices — ask an index or walk the disk, and match a name or match the contents — and six tools scattered across the resulting grid. Pick the cell first. The command follows.

Every tool in this guide is fast at one thing and embarrassing at another, and the reason is always the same two axes.

Axis one: index or walk

An index is a database somebody built earlier by walking the disk so you would not have to. Querying it is fast because the work already happened. That speed is bought with three liabilities: the index has a freshness date, it has a scope (things it was never allowed to see), and it has a schema (questions it cannot express). mdfind and locate query indexes.

A walk opens directories and reads entries, right now, in the order the filesystem hands them over. It is always current, it sees exactly what your user account is permitted to see, and it costs I/O proportional to the size of the tree. find, fd, grep and rg walk.

Axis two: name or contents

Matching a name means reading directory entries — cheap, because the filesystem hands you names for free while traversing. Matching contents means opening and reading every candidate file, which is one to three orders of magnitude more work. mdfind is the odd one out: it is the only tool here that searches contents from an index, because Spotlight extracted and stored the text of your files when they were written.

The four failure modes

Every "why can't I find my file" on a Mac is one of these. Section 18 is the full symptom table; these are the shapes.

Sources: mdfind(1) · locate(1) · ripgrep user guide

2 · What the shell does before the tool runs

Half of all file-search bugs are not search bugs. The shell rewrites your command line before the tool ever sees it, and the two languages involved — shell globs and regular expressions — use overlapping punctuation to mean opposite things.

Self-assessment

Answer these before reading on. If all five are instant, skim to §3; if any makes you pause, this section is the floor the rest of the guide stands on.

find: retry.js: unknown primary or operator

zsh: no matches found: *.js

printf 'a.b\naxb\n' | grep 'a.b'
a.b
axb

rg: regex parse error:
    (?:*.js)
       ^
error: repetition operator missing expression

ls -li docs/notes.md
465192060 -rw-r--r--@ 1 you  wheel  52 Sep 10 12:54 docs/notes.md
xattr -l docs/notes.md
com.apple.provenance:

Globs and regexes are different languages

They share *, ? and […] and agree on almost none of them. Knowing which language a given argument is written in is the single highest-leverage fact in this guide.

That last row is the one that bites. find -name '*.txt' is anchored, so it only matches names ending in .txt. locate '.pb.go' is a substring match, so it also returns annotations.pb.go.meta. Same intent, different answer — measured in §15.

Sources: find(1) · POSIX shell — pattern matching

3 · Install & verify

Four of the six ship with macOS. The two that do not are the two you will use most. Before anything else, find out which binary your shell actually runs — on a machine with Homebrew, MacPorts and a dotfile collection, that is a real question with a surprising answer.

What is already there

# the two you have to add
brew install fd ripgrep

# optional, but this guide uses it in §14
brew install fzf

# worth adding once you have read §10: the fastest grep here, and the portable one
brew install ugrep grep    # "grep" installs GNU grep as ggrep

Verify — and find out what grep really is

sw_vers
ProductName:		macOS
ProductVersion:		15.6
BuildVersion:		24G84

fd --version   → fd 10.5.0
rg --version   → ripgrep 15.2.0
                 features:+pcre2
                 PCRE2 10.45 is available (JIT is available)

/usr/bin/grep --version
grep (BSD grep, GNU compatible) 2.6.0-FreeBSD

Now the important one. which grep lies if there is a shell alias or function in the way; type tells the truth:

type grep egrep fgrep
grep is an alias for grep --color=auto --exclude-dir={.bzr,CVS,.git,.hg,.svn,.idea,.tox,.venv,venv}
egrep is an alias for grep -E
fgrep is an alias for grep -F

Sources: fd — installation · ripgrep — installation · grep(1) on macOS

4 · find — the baseline everything else is measured against

find is not a search command. It is a tiny declarative language for walking a directory tree and running a boolean expression against every entry it meets. Once you see the expression, the syntax that looks arbitrary becomes almost inevitable.

The shape is always the same:

find [options] where what-to-match what-to-do

find . -type f -name '*.js' -print reads as: start at .; for every entry, test is a regular file AND basename matches *.js AND print it. Predicates are ANDed by juxtaposition, they short-circuit left to right, and -print is a predicate too — it "succeeds" and has the side effect of printing. That is why find . -name '*.js' -print -o -print does not double up: the first -print already returned true.

The predicates that earn their keep

# everything modified in the last 30 days is *not* -mtime +30
find . -type f -mtime +30
./docs/draft.txt

# "changed since the last build" without a timestamp file of your own
find . -type f -newer docs/draft.txt -name '*.md'
./docs/notes.md

# BSD find has -s: walk in sorted order (GNU findutils does not)
find -s . -maxdepth 1 -name '[a-z]*'
./build
./docs
./logs
./node_modules
./src
./with space dir

-exec {} + versus | xargs

Three ways to do something with the matches, in ascending order of how much you should like them:

find . -name '*.js' -not -path './.git/*' -exec wc -l {} +
       1 ./node_modules/left-pad/index.js
       1 ./build/bundle.js
       0 ./src/empty.js
       4 ./src/api/client.js
       2 ./src/api/retry.js
       8 total

Now watch the naive pipeline meet the directory called with space dir:

find . -name '*.txt' | xargs wc -c
wc: ./with: open: No such file or directory
wc: space: open: No such file or directory
wc: dir/a: open: No such file or directory
wc: file.txt: open: No such file or directory
       6 ./docs/draft.txt
       6 total

# the NUL-separated form is correct
find . -name '*.txt' -print0 | xargs -0 wc -c
      15 ./with space dir/a file.txt
       6 ./docs/draft.txt
      21 total

BSD find is not GNU find

Commands copied from Linux answers fail here in specific, recognisable ways.

# BSD extended-regex form — note -E before the path
find -E . -regex '.*/(client|retry)\.js'
./src/api/client.js
./src/api/retry.js

Sources: find(1) on macOS · xargs(1) · POSIX find

5 · fd — the same walk, with opinions

fd is not a faster find. It is a differently scoped find: it walks in parallel, matches a regex against the path instead of a glob against the basename, and — the part that surprises people — deliberately refuses to show you files you almost certainly did not mean.

Run both on the sandbox and the difference is immediate:

find . -name '*.js'            fd -e js
./node_modules/left-pad/index.js   src/api/client.js
./build/bundle.js                  src/api/retry.js
./src/empty.js                     src/empty.js
./src/api/client.js
./src/api/retry.js
5 results                          3 results

fd dropped build/bundle.js and node_modules/left-pad/index.js because the sandbox's .gitignore lists them. That is a feature roughly 95% of the time and a trap the other 5%. Turn it off explicitly:

fd -e js --no-ignore --hidden
build/bundle.js
node_modules/left-pad/index.js
src/api/client.js
src/api/retry.js
src/empty.js

What fd hides, and the flags that unhide it

Smart case — and why rg does the opposite

fd is case-insensitive until your pattern contains an uppercase letter, at which point it becomes case-sensitive. This is genuinely convenient and genuinely surprising the first time it bites:

fd -H -I 'ENV'
(nothing — the capitals made it case-sensitive, and the file is .env)

fd -H -I 'env'
.env

Everyday fd

# type filter: f file · d directory · l symlink · x executable · e empty
fd -t d
docs/
logs/
src/
src/api/
src/web/
with space dir/

# extension filter beats writing a regex for it
fd -t f -e md
docs/notes.md

# time filters, in plain English
fd --changed-within 1h -t f
fd --changed-before 2weeks -t f

# literal string, no regex parsing at all
fd -F 'a file'
with space dir/a file.txt

# ls -l style detail, without a second command
fd -e md -l
-rw-r--r-- 1 you wheel 52 Sep 10 12:54 ./docs/notes.md
lrwxr-xr-x 1 you wheel 16 Sep 10 12:54 ./src/link-to-notes.md -> ../docs/notes.md

-x and -X: exec without xargs

fd folds -exec and xargs into two flags, and handles the quoting for you:

fd -e js -x wc -l {}     # one process per file, in parallel
fd -e js -X wc -l        # one process for all files (note the total line)
       2 ./src/api/retry.js
       4 ./src/api/client.js
       0 ./src/empty.js
       6 total

Placeholders inside -x: {} the path, {/} the basename, {//} the parent, {.} the path without its extension, {/.} the basename without its extension.

fd -e pdf ~
[fd error]: The search pattern '/Users/you' contains a path-separation
character and will not lead to any search results.

If you want to search for all files inside the '/Users/you' directory,
use a match-all pattern:

  fd . '/Users/you'

Sources: sharkdp/fd — README · fd — command-line options

6 · locate — a weekly photograph of your filenames

locate does not search your disk. It greps a compressed text file that a launchd job produced last Saturday morning by walking the disk as the user nobody. Every one of that sentence's clauses is a limitation you will meet, and together they explain everything locate gets right and wrong.

The lifecycle

The job ships disabled

Apple installs the launchd plist with Disabled set to true. On a Mac where nobody has turned it on, the database file simply is not there, and locate tells you so rather than returning an empty result:

locate anything
locate: `/var/db/locate.database': No such file or directory

Enable the job once and it maintains itself:

# is it on?
sudo launchctl print-disabled system | grep locate
		"com.apple.locate" => enabled

# turn it on (also triggers a first build via the plist's KeepAlive PathState)
sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.locate.plist

Reading the database's own vital signs

locate -S
Database: /var/db/locate.database
Compression: Front: 12.01%, Bigram: 67.34%, Total: 9.05%
Filenames: 11281033, Characters: 1256828120, Database size: 113744501

# how stale is it, really?
stat -f '%Sm  owner=%Su' -t '%Y-%m-%d %H:%M' /var/db/locate.database
2026-09-05 03:35  owner=nobody

That timestamp is the single most useful thing about locate. Anything created after it is invisible, and the answer is never "wait a moment and retry."

The nobody boundary, measured

The database only contains paths that the unprivileged user nobody could traverse. Your home directory is mode 755, so it is in. ~/Documents and ~/Library are mode 700, so they are not — at all:

ls -ld ~ ~/Documents ~/Library
drwxr-xr-x@ 782 you  staff   /Users/you
drwx------@  97 you  staff   /Users/you/Documents
drwx------@ 145 you  staff   /Users/you/Library

locate -c '/Users/you/guides/'      → 337
locate -c '/Users/you/Documents/'   → 0
locate -c '/Users/you/Library/'     → 0

What else is excluded

Read the rules yourself — they are plain shell variables near the top of /usr/libexec/locate.updatedb:

Using it well

# plain substring — matches anywhere in the full path
locate -l 5 mdfind
locate: [show only 5 lines]
/Applications/Xcode.app/…/man1/mdfind.1
/Library/Developer/CommandLineTools/SDKs/MacOSX15.5.sdk/…/mdfind.1
/Users/you/man/mdfind.pdf

# contains a metacharacter → treated as a glob against the whole path
locate '/usr/bin/md*'
/usr/bin/mddiagnose
/usr/bin/mdfind
/usr/bin/mdimport
/usr/bin/mdls
/usr/bin/mdutil

# count instead of listing; -i for case-insensitive; -0 for xargs safety
locate -c 'bin/grep'
locate -0 '*.pdf' | xargs -0 ls -lh

Sources: locate(1) · locate.updatedb(8) · /usr/libexec/locate.updatedb and /System/Library/LaunchDaemons/com.apple.locate.plist on the machine itself

7 · grep and egrep — the BSD one

The grep on your Mac is not the grep that almost every tutorial on the internet was written against. It is BSD grep, inherited from FreeBSD, and the differences are small in number and large in consequence.

/usr/bin/grep --version
grep (BSD grep, GNU compatible) 2.6.0-FreeBSD

"GNU compatible" is an aspiration, not a guarantee. Two of the gaps are load-bearing.

Gap 1: there is no -P

printf 'abc123\n' | grep -P '\d+'
grep: invalid option -- P
usage: grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz] [-A num] [-B num] [-C[num]]
	[-e pattern] [-f file] [--binary-files=value] [--color=when]
	[--context[=num]] [--directories=action] [--label] [--line-buffered]
	[--null] [pattern] [file ...]
# exit status 2 — "an error occurred", not "no match"

If you need Perl-compatible regex from a grep-shaped tool on macOS the answer is rg -P (§9), ugrep -P, ggrep -P or pcre2grep — all four verified working here (§10). It is never grep.

printf 'foobar\nfoobaz\n' | ggrep -P 'foo(?=bar)'   → foobar
printf 'foobar\nfoobaz\n' | ugrep -P 'foo(?=bar)'   → foobar

Gap 2: -r and -R are the same flag

On GNU grep, -r recurses without following symlinked directories and -R follows them. On macOS the man page lists them on one line — -R, -r, --recursive — and behaviour confirms it: neither descends into a symlinked directory. Both sides, measured against the same symlinked directory:

# src/linkdir is a symlink to a sibling directory holding one matching file
grep  -r 'TIMEOUT in linked' src/   → (nothing, rc=1)
grep  -R 'TIMEOUT in linked' src/   → (nothing, rc=1)   ← BSD: same flag
ggrep -r 'TIMEOUT in linked' src/   → (nothing, rc=1)
ggrep -R 'TIMEOUT in linked' src/   → src/linkdir/deep.txt:TIMEOUT in linked dir

A script that relies on -R following links searches less than its author intended the moment it runs on macOS — silently, with exit status 1, which looks exactly like "no matches".

Gap 3 (in your favour): egrep is not deprecated here

GNU grep from 3.8 onwards warns that egrep is obsolescent every time you run it. BSD grep does not. Both halves measured on this machine — first BSD, silent and exit 0:

echo foo | /usr/bin/egrep 'o+'
foo
# no warning, exit status 0

…then GNU grep 3.12, installed alongside as ggrep, on the same input:

echo foo | gegrep 'o+'
gegrep: warning: gegrep is obsolescent; using ggrep -E
foo
# warning on stderr, match still printed, exit status 0

So egrep is perfectly safe on macOS today — and the same script starts emitting warnings the moment it runs on a modern Linux box or through ggrep. Write grep -E and the question never arises.

The flags worth memorising

# the ones you will actually type
grep -rn 'TIMEOUT' . --exclude-dir=.git
./with space dir/a file.txt:1:spaced TIMEOUT
./docs/notes.md:2:Set TIMEOUT in the config.
./logs/app.log:3:ERROR TIMEOUT again
./.env:1:.hidden secret TIMEOUT
./build/bundle.js:1:compiled junk TIMEOUT
./src/web/index.html:2:<p>TIMEOUT is not set here.</p>
./src/api/client.js:1:const TIMEOUT = 30;

# only the matched text — grep as an extractor
grep -o 'TIME[A-Z]*' logs/app.log
TIMEOUT

# one line of context each side
grep -C1 'ERROR TIMEOUT' logs/app.log
INFO ok
ERROR TIMEOUT again

Exit status is the interface

Note also that all seven files above include .env, build/ and logs/. grep -r has never heard of .gitignore. That is the whole difference between §7 and §9, and sometimes it is the reason to reach for the old tool.

Sources: grep(1) on macOS · GNU grep manual (for the contrast) · POSIX grep

8 · The four regex dialects on one Mac

A regular expression is not a language. It is four languages that share an alphabet, and your Mac has all four installed. A pattern that works in one and fails in another is not a bug — it is a translation error, and the table below is the dictionary.

The measured truth table

Every cell below was produced by running the pattern against the same eight-line input on macOS 15.6 with grep 2.6.0-FreeBSD and ripgrep 15.2.0. Two of them contradict what people confidently say about macOS.

rg: regex parse error:
    (?:foo(?=bar))
          ^^^
error: look-around, including look-ahead and look-behind, is not supported

Consider enabling PCRE2 with the --pcre2 flag, which can handle backreferences
and look-around.

Try it

Writing patterns that survive the trip

Sources: Rust regex crate — syntax and its deliberate omissions · POSIX chapter 9 — BRE and ERE · PCRE2 syntax summary · re_format(7) on macOS

9 · ripgrep — the same walk, done properly

rg is faster than grep -r for two reasons, and only one of them is speed. It searches in parallel with a vectorised literal scanner — and it refuses to search most of the files grep would have opened. On the benchmark in §15 it was 20× faster than BSD grep -r, and part of that margin is work it declined to do. It is not the fastest tool in that table, though — see §10.

The five filters, in the order they apply

Default behaviour, demonstrated

rg TIMEOUT
with space dir/a file.txt:spaced TIMEOUT
src/web/index.html:<p>TIMEOUT is not set here.</p>
src/api/client.js:const TIMEOUT = 30;
docs/notes.md:Set TIMEOUT in the config.

rg -uu TIMEOUT
.env:.hidden secret TIMEOUT
src/api/client.js:const TIMEOUT = 30;
logs/app.log:ERROR TIMEOUT again
src/web/index.html:<p>TIMEOUT is not set here.</p>
with space dir/a file.txt:spaced TIMEOUT
docs/notes.md:Set TIMEOUT in the config.
build/bundle.js:compiled junk TIMEOUT

git check-ignore -v .env
/Users/you/.gitignore_global:56:.env	.env

Case sensitivity: the opposite of fd

rg timeout            # case-SENSITIVE by default
src/api/retry.js:const timeout = 5000;
docs/notes.md:timeout matters.

rg -S timeout         # smart case: lowercase pattern → insensitive
src/api/retry.js:const timeout = 5000;
docs/notes.md:Set TIMEOUT in the config.
docs/notes.md:timeout matters.
with space dir/a file.txt:spaced TIMEOUT
src/api/client.js:const TIMEOUT = 30;
src/web/index.html:<p>TIMEOUT is not set here.</p>

Two hits versus six, from one flag. If you want smart case permanently, put it in a config file (below) rather than retyping -S.

The flags that change how you work

# rewrite while extracting — grep -o with capture groups
rg -uu -o -r 'LEVEL=$1' '^(ERROR|INFO)' logs/app.log
LEVEL=ERROR
LEVEL=INFO
LEVEL=ERROR

# the honest profiler
rg --stats TIMEOUT
4 matches
4 matched lines
4 files contained matches
8 files searched
171 bytes printed
275 bytes searched
0.000598 seconds spent searching
0.004693 seconds total

8 files searched out of 13 on disk. That number, not the timing, is where most of ripgrep's advantage comes from on a real project.

Make your defaults permanent

ripgrep reads no config file unless you tell it where one is:

# ~/.zshrc
export RIPGREP_CONFIG_PATH="$HOME/.config/ripgrep/config"

# ~/.config/ripgrep/config — one argument per line, # for comments
--smart-case
--max-columns=200
--max-columns-preview
--type-add=web:*.{html,css,js,ts,tsx}
--glob=!.git/*

Sources: ripgrep user guide · ripgrep FAQ · BurntSushi/ripgrep

10 · The rival greps — one of them wins

This section originally said "you do not need any of these." Then they were installed and measured, and one of them beat ripgrep by a factor of four while returning a byte-identical result set. The lesson is the one §15 keeps making: run the benchmark on your own corpus, and be willing to be wrong.

ack --version    → ack v3.10.0 (standard build), running under Perl v5.34.3
ggrep --version  → ggrep (GNU grep) 3.12
ugrep --version  → ugrep 7.8.4 x86_64-apple-darwin24.6.0; -P:pcre2jit;
                    -z:zlib,bzip2,lzma,lz4,zstd,7z,tar/pax/cpio/zip

Measured, on the same corpus

Same query, same 39,798-file tree, same method as §15: best of three warm runs, output to /dev/null.

ugrep -r --stats 'func NewClient' ~/go
Searched 36644 files in 8673 directories in 0.73 seconds with 12 threads: 71 matching (0.1938%)
Searched 20397063 lines: 88 matching (0.0004314%)

rg --stats 'func NewClient' ~/go
32365 files searched

What each one is actually for

The filtering models differ, and that changes answers

Run each against the §3 sandbox and the disagreement is the whole story. TIMEOUT appears in seven files:

printf 'aaa\na+b\ncat\n' | ugrep 'a+'      → aaa · a+b · cat
printf 'aaa\na+b\ncat\n' | ugrep -G 'a+'   → a+b

What ugrep does that nothing else here does

Search inside archives. -z descends into zip, tar, 7z and the compressed variants — and reports the member path:

zip -q arch.zip docs/notes.md
ugrep -z -r 'TIMEOUT' arch.zip
arch.zip{docs/notes.md}:Set TIMEOUT in the config.

# ripgrep's -z handles gz/bz2/xz streams, not archive members:
rg -z 'TIMEOUT' arch.zip
binary file matches (found "\0" byte around offset 5)

Fuzzy matching. -Z takes an edit distance, so a transposition still matches:

printf 'NewClient\nNewCleint\nNewClientsPool\n' | ugrep -Z2 'NewClient'
NewClient
NewCleint          ← two transposed letters, still found
NewClientsPool

It also ships ug --query, an interactive full-screen search (the ug command is ugrep with a user config file), and ugrep-indexer, which builds an index to accelerate repeated searches over a fixed tree — a fourth point on the index-versus-walk axis from §1.

Sources: Genivia/ugrep · ugrep user manual · GNU grep manual · ack — beyondgrep.com · ggreer/the_silver_searcher

11 · Spotlight and Finder — the same index, two front doors

The magnifying glass in your menu bar and the mdfind in your terminal are two clients of one database. Everything you can express by clicking in Finder can be written as a query string — and Finder will hand you that string if you know where to look.

Three front doors

Finder's scope switch is a preference, and it has bitten everyone

When you press ⌘F, Finder searches either "This Mac" or the folder you were in — depending on a setting you probably never opened. Read and set it from the terminal:

defaults read com.apple.finder FXDefaultSearchScope
SCcf

# SCev = This Mac · SCcf = Current Folder · SCsp = Previous scope
defaults write com.apple.finder FXDefaultSearchScope -string SCcf
killall Finder

The GUI equivalent is Finder > Settings > Advanced > "When performing a search". If Finder search "never finds anything," this is the first thing to check — you have been searching one folder all along.

The bridge: a Smart Folder is a query in a plist

This is the part worth the price of admission. A saved search is a property list whose RawQuery key holds a Spotlight query string — the exact dialect mdfind speaks. Read one:

plutil -p ~/Library/Saved\ Searches/*.savedSearch | head -20
{
  "CompatibleVersion" => 1
  "RawQuery" => "(kMDItemUserTags = \"Gray\"cd) || ((_kMDItemFinderLabel = 1) && (kMDItemUserTags != \"*\"))"
  "RawQueryDict" => {
    "FinderFilesOnly" => 0
    "RawQuery" => "(kMDItemUserTags = \"Gray\"cd) || ((_kMDItemFinderLabel = 1) && (kMDItemUserTags != \"*\"))"
    "SearchScopes" => [
      0 => "kMDQueryScopeComputer"
      1 => "kMDQueryScopeNetworkIndexed"
    ]
    "UserFilesOnly" => 1
  }
  "SearchCriteria" => { … the GUI's own representation of the same thing … }

Paste that RawQuery straight into mdfind and it runs:

mdfind '(kMDItemUserTags = "Gray"cd)'
/Users/you/Library/Mobile Documents/…/Nice_List_Certificate.pdf
/Volumes/thunderbay-private2/tmp/39953.mp4

The plain-language operators work in both places

What you type into the Spotlight field is a query language too, and mdfind parses the same thing:

mdfind -onlyin ~ 'kind:pdf'
mdfind -onlyin ~ 'kind:pdf date:today'
mdfind -onlyin . 'name:report'
mdfind -onlyin . 'Zylophantic AND quarterly'

kind:, date:, name:, author:, quoted "exact phrases" and uppercase AND / OR / NOT behave the same in the menu-bar field and on the command line. That is one language to learn, not two.

(* = search* cdw || kMDItemTextContent = search* cdw)

Sources: Apple — Search for anything with Spotlight on Mac · Apple — Create or change a Smart Folder on Mac · Apple — Mac keyboard shortcuts · mdfind(1)

12 · mdfind — Spotlight from the shell

mdfind is the most powerful search tool on your Mac and the one most likely to lie to you, because it is the only one that does not search files. It searches a description of your files that a fleet of importer plugins wrote when those files were saved — and a description is not the thing.

Getting started

# everything, anywhere, any attribute — usually far too much
mdfind Zylophantic

# scope it. -onlyin is the single most important flag.
mdfind -onlyin ~/spotlight-lab-tmp Zylophantic
/Users/you/spotlight-lab-tmp/report.txt
/Users/you/spotlight-lab-tmp/scratch.md
/Users/you/spotlight-lab-tmp/memo.rtf

# filenames only
mdfind -onlyin ~/spotlight-lab-tmp -name memo
/Users/you/spotlight-lab-tmp/memo.rtf

# count · NUL-safe · show attributes inline
mdfind -count -onlyin ~ 'kind:pdf'
mdfind -0 -onlyin ~ 'kind:pdf' | xargs -0 ls -lh
mdfind -onlyin ~/spotlight-lab-tmp -attr kMDItemContentType -attr kMDItemFSSize Zylophantic
…/report.txt   kMDItemContentType = public.plain-text   kMDItemFSSize = 65
…/scratch.md   kMDItemContentType = net.daringfireball.markdown   kMDItemFSSize = 40
…/memo.rtf     kMDItemContentType = public.rtf   kMDItemFSSize = 383

The lesson that matters most: words, not substrings

This is the difference between mdfind and every other tool in this guide, and skipping it will cost you an afternoon. Here is the same question asked four ways against the same 39,798-file tree:

The 84 and the 71 do not merely differ in size — they differ in membership. 70 files are in both. Both discrepancies are explainable, and each teaches a rule:

The exact matching rule, measured

"Tokens, not substrings" is the headline, but the detail decides whether your query works. One file containing the single line alpha NewClientsPool beta, asked six ways:

Two operational quirks you will hit in the first five minutes

1. It writes noise to stderr. Any query that goes through the user-syntax parser prints locale chatter:

mdfind -onlyin ~ 'kind:pdf'
2026-09-10 13:03:02.808 mdfind[10674:80508855] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2026-09-10 13:03:02.808 mdfind[10674:80508855] [UserQueryParser] Loading keywords and predicates for locale "en"
/Users/you/Downloads/ISO_12233-reschart.pdf

Raw kMDItem… queries do not print it. In scripts, always 2>/dev/null. Some queries also emit Couldn't determine the mapping between prefab keywords and predicates. — harmless, and it does not stop the results.

2. It cannot see your temp directory. /private/tmp and /private/var/folders are not indexed, which is exactly where mktemp -d puts things. Build Spotlight sandboxes under $HOME.

Where the index has holes

mdutil -a -s
/:
	Indexing enabled. 
/System/Volumes/Data:
	Indexing enabled. 
/Volumes/thunderbay-private:
	Indexing and searching disabled.
/Volumes/timemachine-8tb:
	Indexing and searching disabled.

Two of this machine's six volumes are invisible to mdfind and always will be until someone turns them on. If a search "cannot find" something on an external drive, run this first.

# marker file present, then a new file created inside
mdfind -onlyin ~/spotlight-lab-tmp/never2 Qwixotrone
/Users/you/spotlight-lab-tmp/never2/late.txt   ← still indexed

# same test, folder renamed to end in .noindex
mdfind -onlyin ~/spotlight-lab-tmp/x.noindex Qwixotrone
(nothing)   ← blocked

Privacy protections apply to walking too

Some directories are unreadable even by you, because macOS's TCC layer gates them behind Full Disk Access. Every walking tool hits the same wall:

find ~/Library/Mail -maxdepth 1
/Users/you/Library/Mail
find: /Users/you/Library/Mail: Operation not permitted

find /Library/Application\ Support/com.apple.TCC -type f
find: /Library/Application Support/com.apple.TCC: Operation not permitted

Operation not permitted — as opposed to Permission denied — is the signature of TCC rather than of Unix file modes. Granting your terminal Full Disk Access in System Settings → Privacy & Security removes it, and is a decision worth making deliberately rather than to silence one error.

Sources: mdfind(1) · mdutil(1) · mdimport(1) · mdls(1)

13 · The Spotlight query language

Raw queries are where mdfind stops being a worse grep and becomes something nothing else on the machine can do: "PDFs over 5 MB, authored by someone, modified since Monday, tagged red." Nothing walks fast enough to answer that. The syntax is small; the vocabulary is the hard part, and mdls hands it to you.

Step one: ask a file what it knows about itself

mdls report.txt
kMDItemContentCreationDate     = 2026-09-10 17:56:33 +0000
kMDItemContentType             = "public.plain-text"
kMDItemContentTypeTree         = (
    "public.plain-text",
    "public.text",
    "public.data",
    "public.item",
    "public.content"
)
kMDItemDisplayName             = "report.txt"
kMDItemFSName                  = "report.txt"
kMDItemFSSize                  = 65
kMDItemKind                    = "Plain Text Document"
kMDItemLogicalSize             = 65
kMDItemPhysicalSize            = 4096
…

Every left-hand name is a queryable attribute. mdls on a photo, a PDF and a Pages document will show you three very different lists — that is the schema, per file type. mdimport -X dumps the whole schema if you want the exhaustive version.

Step two: the grammar

# modifiers are not decoration — without c, the case must match exactly
mdfind -onlyin "$SL" "kMDItemFSName == 'REPORT.TXT'c"
/Users/you/spotlight-lab-tmp/report.txt

mdfind -onlyin "$SL" "kMDItemFSName == 'REPORT.TXT'"
(nothing)

# d folds accents: this finds café.txt
mdfind -onlyin "$SL" "kMDItemFSName == 'cafe.txt'd"
/Users/you/spotlight-lab-tmp/café.txt

# PDFs touched in the last week, anywhere in $HOME
mdfind -onlyin ~ "kMDItemContentModificationDate >= \$time.today(-7) && kMDItemContentType == 'com.adobe.pdf'"

Content types: the tree is what you want

kMDItemContentType is one exact Uniform Type Identifier. kMDItemContentTypeTree is that type plus everything it conforms to, and it is almost always the more useful field:

mdfind -onlyin "$SL" "kMDItemContentType == 'public.plain-text'"
report.txt                       ← exact type only

mdfind -onlyin "$SL" "kMDItemContentTypeTree == 'public.text'"
report.txt
scratch.md
memo.rtf                        ← everything that IS text

Useful UTIs: public.image, public.movie, public.audio, public.text, public.source-code, com.adobe.pdf, public.folder. Markdown is net.daringfireball.markdown.

Wildcards: what actually works

Apple's reference says * matches "at the beginning, the end, or anywhere within" a string and that ? matches a single character. Measured on macOS 15.6 against a file named report.txt, that is not quite the behaviour:

mdfind -onlyin "$SL" "InRange(kMDItemFSSize,1,100000)"
(nothing — report.txt is 65 bytes)

mdfind -onlyin "$SL" "kMDItemFSSize > 50 && kMDItemFSSize < 100"
/Users/you/spotlight-lab-tmp/report.txt

Build a query

mdfind -onlyin ~/Documents "kMDItemFSName == '*.pdf'c" 2>/dev/null

A working vocabulary

Sources: Apple — File Metadata Query Expression Syntax · mdls(1) · mdimport(1) — -X dumps the whole attribute schema

14 · Pipelines — using two tools where one will not do

The best macOS search is almost never one command. It is an index narrowing the field in milliseconds, handing a short list to a walker that answers precisely. Learn three joins and you can compose anything in this guide.

Join 1: index → walker (the important one)

mdfind finds candidate files fast but cannot show you a line. rg shows you lines but must open everything. Chain them and each does the part it is good at:

# "which of my indexed documents mentions this, and where exactly?"
mdfind -0 -onlyin ~/Documents 'invoice' 2>/dev/null \
  | xargs -0 rg -H -n -i 'net 30'

Spotlight cuts a 40,000-file directory to a handful; ripgrep gives you file, line number and context on those. This also rescues you from the token rule of §12 — Spotlight finds the candidates loosely, rg applies the exact pattern.

Join 2: walker → walker

# fd decides which files; rg decides which lines
fd -t f -e md -0 | xargs -0 rg -H -n -i timeout
docs/notes.md:3:timeout matters.

# or let fd do the batching itself
fd -t f -e md -X rg -H -n -i timeout

Worth knowing: for plain "search these file types," rg -t markdown or rg -g '*.md' is one process and faster. Reach for the pipeline when the file selection needs something rg's globs cannot express — a size, an mtime, an executable bit.

Join 3: anything → fzf

Every tool here can feed an interactive picker. This is where search stops being a command and becomes a way of moving around.

# pick a file from everything ripgrep would search, with a preview
rg --files | fzf --preview 'head -80 {}' --preview-window=right:60%

# jump to a directory
cd "$(fd -t d . ~ | fzf)"

# pick from Spotlight's answer instead of a walk
mdfind -onlyin ~ 'kind:pdf' 2>/dev/null | fzf --preview 'mdls {}'

Two functions worth putting in ~/.zshrc. The first is live grep — every keystroke re-runs rg and the picker shows matching lines; the second opens the chosen result at the right line:

# live ripgrep: type, see matching lines, press enter to open at that line
rgf() {
  local f
  f=$(fzf --ansi --disabled --layout=reverse \
        --bind "change:reload:rg --column --line-number --color=always {q} || true" \
        --delimiter : \
        --preview 'rg --color=always --context 5 {q} {1} 2>/dev/null | head -60') || return
  local file=${f%%:*} line=$(echo "$f" | cut -d: -f2)
  ${EDITOR:-vi} "+$line" "$file"
}

# Spotlight picker: fuzzy-filter an indexed search, open the winner
sf() {
  mdfind -onlyin "${2:-$HOME}" "$1" 2>/dev/null \
    | fzf --preview 'mdls -name kMDItemKind -name kMDItemFSSize -name kMDItemContentModificationDate {}' \
    | xargs -o open
}

The fzf guide in this collection covers the picker itself; here it is only the last stage of a search pipeline.

Join 4: search → structured output

# ripgrep speaks JSON — one object per event
rg --json TIMEOUT docs/notes.md | head -2
{"type":"begin","data":{"path":{"text":"docs/notes.md"}}}
{"type":"match","data":{"path":{"text":"docs/notes.md"},"lines":{"text":"Set TIMEOUT in the config.\n"},"line_number":2,"absolute_offset":8,"submatches":[{"match":{"text":"TIMEOUT"},"start":4,"end":11}]}}

# which makes counting per file a jq one-liner rather than an awk puzzle
rg --json -uu TIMEOUT . \
  | jq -r 'select(.type=="match") | .data.path.text' \
  | sort | uniq -c | sort -rn

The universal starting pattern

# 1 · narrow with the cheapest tool that can express the filter
# 2 · hand over a NUL-separated list
# 3 · finish with the tool that answers precisely

<narrower> -0 | xargs -0 <precise tool> -H -n <pattern>

Sources: junegunn/fzf · ripgrep user guide · xargs(1)

15 · Benchmarks — and what they do not mean

Numbers from someone else's machine are entertainment. These are from one specific Mac, on one specific corpus, and the reason they are here is not the ranking — it is that the tools return different answers, and the differences are the lesson.

Method

Intel Mac, macOS 15.6 (24G84), APFS internal SSD. Corpus: ~/go — 39,798 files, 3.0 GB, 22,079 of them .go. Each command run three times with output to /dev/null; the best time is reported. Every figure in both tables below comes from a single sitting, so the tools are comparable with each other even though absolute numbers drift a few percent between sittings. The page cache was warmed first with a full find pass, so these are warm-cache numbers — a cold run costs several times more for the walkers and roughly nothing for the index queries.

Finding files by name

…/gogoproto/gogo.pb.golden
…/minio-srv/vendor/…/gogoproto/gogo.pb.golden
…/protoc-gen-go/testdata/annotations/annotations.pb.go.meta

Finding text inside files

Four points hide in that table.

One. mdfind looks competitive and is not competing. Its 726 files are documents containing the words func and NewClient somewhere; the greps found 88 specific lines in 71 files. Comparing their times is comparing a library catalogue to a book.

Two. Every grep-shaped tool here agrees: 88 matching lines in 71 files, no exceptions. An 80-fold spread in time and not one disagreement about the answer. When a search tool is slow it is doing the same work badly, not doing different work.

Three. rg -uu — every filter disabled — is 1.3× slower than default rg here, because ~/go has few ignored files. On a JavaScript monorepo with a 400 MB node_modules, that same flag is the difference between one second and thirty. The filters, not the threads, are ripgrep's biggest lever on real projects.

Four. BSD grep's 20× deficit is not incompetence, it is architecture: single-threaded, opens every file, no literal prefilter. GNU grep 3.12 closes about five-sixths of that gap without changing the model at all. The rest of the distance — rg and ugrep — is parallelism plus SIMD literal scanning (rg --version reports simd(runtime):+SSE2,+SSSE3,+AVX2). That ugrep is four times faster again than rg on this corpus is the result that made §10 get rewritten.

Sources: measured on the machine described above, 2026-09-10 · Andrew Gallant — ripgrep is faster than {grep, ag, git grep, ucg, pt, sift}, for the methodology this section imitates

16 · Choosing, without thinking about it

Three questions, asked in order, pick the tool every time. You will internalise them in a week and never consult this section again — which is the point.

The decision matrix

Translation table, if you came from Linux

17 · Capstone — the four-phase hunt

One scenario, four phases, every tool in the guide. The premise: you half-remember a PDF invoice from earlier this year, you think a config file somewhere mentions the same client, and you want to know why one of your searches keeps coming up empty.

18 · Troubleshooting

Almost every complaint is "it should have found that." The table maps symptom to mechanism to fix. Work down it in order — the cheap checks are first.

Nothing found, but the file exists

Errors and refusals

Too many results, or the wrong ones

Performance

19 · Cheat sheet

The universal starting pattern

# narrow with the cheapest tool, hand over NUL-separated, finish precisely
<narrower> -0 | xargs -0 <precise tool> -H -n <pattern>

# the three you will type every day
rg PATTERN                        # text, here, now
fd PATTERN [DIR]                  # a filename, in a tree you can name
mdfind -onlyin DIR 'kind:pdf'      # a property only the index knows

Shell safety, in four lines

# quote every pattern containing * ? [ ] or a space
find . -name '*.log'

# NUL-separate every filename that crosses a pipe
fd -0 … | xargs -0 …

# force the filename when a pipeline may pass exactly one file
… | xargs -0 rg -H -n PATTERN

# never let a no-match kill a set -e script
if rg -q PATTERN file; then … ; fi

20 · Glossary

anchored pattern

A pattern that must match the whole subject, not part of it. find -name '*.txt' is anchored to the basename, which is why it will not match a.txt.bak; locate '.txt' is unanchored and will. (§2)

BRE — basic regular expression

POSIX's older regex dialect, the default for grep and sed. Quantifiers and groups are literal unless escaped: \+, \|, \{3\}, \(…\). (§8)

ERE — extended regular expression

POSIX's modern dialect, reached with grep -E, egrep, find -E or awk. Metacharacters are operators by default and escaping makes them literal. (§8)

dynamic UTI

A generated content-type identifier such as dyn.ah62d4rv4ge80s52, minted when no installed application or system declaration claims a file extension. Not stable between machines, so never query it. (§13)

excludesFile (global gitignore)

The path in core.excludesFile, applied to every repository on the machine. rg and fd honour it, which is why a file can be invisible to them with nothing in the project's own .gitignore. (§9)

firmlink

An APFS link that joins the read-only System volume to the writable Data volume, so /Users and /System/Volumes/Data/Users are the same directory. locate.updatedb prunes firmlink targets specifically to stop every path being indexed twice. (§6)

glob

The shell's filename-matching language: * any run, ? one character, [abc] a set. Implicitly anchored, and expanded by the shell before the command runs unless quoted. Not a regex. (§2)

index

A precomputed answer to a class of questions, with a freshness date and a scope. locate's is a weekly text file; Spotlight's is a live per-volume database. Neither is the disk. (§1)

inode

The filesystem object holding a file's data and metadata. Names in directories point at inodes, so one inode can have several names (hard links). Shown by ls -li. (§2)

kMDItem attribute

One key in Spotlight's per-file metadata record — kMDItemFSSize, kMDItemContentType, kMDItemUserTags, kMDItemTextContent and hundreds more. List them for any file with mdls. (§13)

mdimporter

A plugin that teaches Spotlight to read one family of file formats. 27 ship with macOS 15.6 (mdimport -L); apps install more. If no importer understands a format, its contents are never indexed. (§12)

.noindex

A directory-name suffix that excludes a folder and its contents from Spotlight. Verified working on macOS 15.6 — unlike the .metadata_never_index marker file, which did not block indexing when placed in a subfolder. (§12)

NUL separation

Passing filenames between processes terminated by a zero byte rather than a newline, because NUL is the only character a path cannot contain. find -print0 / fd -0 / mdfind -0 on one side, xargs -0 on the other. (§4)

PCRE2

Perl-Compatible Regular Expressions, version 2 — the dialect with lookahead, lookbehind and backreferences. On a stock-plus-Homebrew Mac it is reached through rg -P. This machine's ripgrep bundles PCRE2 10.45 with JIT. (§8)

prune

To refuse to descend into a directory. find … -prune never opens it at all, which is why it beats filtering the results with -not -path. (§4)

RawQuery

The key inside a Finder saved search (.savedSearch plist) holding the Spotlight query string the GUI generated. Readable with plutil -p and runnable verbatim in mdfind. (§11)

smart case

Case-insensitive matching that turns itself off when the pattern contains an uppercase letter. fd does this by default; rg requires -S. (§5)

TCC

macOS's Transparency, Consent and Control layer — the privacy gate above Unix permissions. Its refusals read Operation not permitted rather than Permission denied, and are lifted by granting Full Disk Access. (§12)

token

The unit Spotlight indexes text in — roughly a word, split on punctuation and case boundaries the importer chose. mdfind matches token prefixes and never the middle of a token, which is why it can miss text that plainly exists. (§12)

UTI — Uniform Type Identifier

macOS's reverse-DNS type name (public.plain-text, com.adobe.pdf) arranged in a conformance hierarchy. kMDItemContentTypeTree matches anywhere in that hierarchy; kMDItemContentType only at the leaf. (§13)

walk

Reading directory entries from the filesystem right now, in whatever order it supplies them. Always current, never stale, and priced in I/O. (§1)

extended attribute (xattr)

Arbitrary key/value data stored alongside a file — Finder tags, quarantine flags, download provenance. Marked by @ in ls -l, listed by xattr -l, and indexed by Spotlight as kMDItem* attributes. Invisible to grep. (§2)

21 · Index

22 · Quiz

Seventeen questions, self-scored. Answer out loud before you reveal — recognising an answer is not the same as producing one. Aim for 15 of 17 before you call this learned.

Reset quiz

23 · Sources

Apple

• File Metadata Query Expression Syntax Best used for: the authoritative operator, modifier, wildcard and $time.* tables. Archived, and §13 records the two places it no longer matches behaviour.
• Search for anything with Spotlight on Mac Best used for: the supported ways to open and use the Spotlight field, per macOS version.
• Create or change a Smart Folder on Mac Best used for: the GUI half of the §11 round trip — File > New Smart Folder, criteria rows, saving.
• Mac keyboard shortcuts Best used for: confirming ⌘Space, ⌥⌘Space, ⌘F and ⌥⌘N in Apple's own words rather than from folklore.

Manual pages

• Keith Smiley's macOS man page mirror Best used for: reading mdfind(1), mdls(1), mdutil(1), mdimport(1), find(1), grep(1), locate(1) and re_format(7) in a browser. The same text is on your disk via man.
• /usr/libexec/locate.updatedb and /System/Library/LaunchDaemons/com.apple.locate.plist Best used for: the ground truth of §6 — PRUNEPATHS, FILESYSTEMS, the su -fm nobody line and the weekly schedule. Both are readable plain text on your own Mac.

The tools

• ripgrep — user guide Best used for: the filtering model, the -u/-uu/-uuu ladder, file types, globs and RIPGREP_CONFIG_PATH. The single best document about any tool in this guide.
• ripgrep — FAQ Best used for: PCRE2, shell completions, and the "why didn't it search X" questions §18 turns into a table.
• sharkdp/fd — README Best used for: the full option list, the -x/-X placeholder syntax, and the design rationale for the default exclusions.
• Rust regex crate — syntax Best used for: exactly which constructs ripgrep supports without -P, and the linear-time guarantee that is the reason for the omissions.
• PCRE2 syntax summary Best used for: what rg -P unlocks — lookaround, backreferences, named groups, possessive quantifiers.
• GNU grep manual Best used for: knowing what the internet's grep advice assumes, and therefore which parts will not work until you brew install grep.
• Genivia/ugrep · ugrep user manual Best used for: the archive (-z), fuzzy (-Z), indexer and interactive-query features that make §10 recommend it, and the full list of the grep options it is compatible with.
• ggreer/the_silver_searcher · ack Best used for: the history §10 compresses — ack invented the VCS-aware, type-filtered search that every tool here now assumes.
• junegunn/fzf Best used for: the --preview, --bind and reload options the §14 shell functions depend on.

Standards and background

• POSIX.1-2017 — Regular Expressions Best used for: settling what BRE and ERE are actually required to do, as opposed to what a given implementation happens to allow.
• POSIX — find · POSIX — grep Best used for: writing scripts that survive on both macOS and Linux — the intersection, not either dialect.
• Andrew Gallant — ripgrep is faster than {grep, ag, git grep, ucg, pt, sift} Best used for: how to benchmark search tools honestly. §15 imitates its method and its caveats.