mdfind on Mac: 8 of 21 Test Files Never Showed Up

I created 21 small files on this Mac mini, each with the same made-up token in its name, and spread them across folders a developer actually uses: a project folder, node_modules, a dot-folder, .git, ~/Library/Caches, /tmp. Then I ran mdfind -name ZQX1630A every ten seconds. It settled at 13 results within the first ten seconds and never moved. The other 8 files exist, find lists all 21, and mdfind exited 0 every time.

That gap is what most "mdfind not working" reports come down to. mdfind doesn't search the disk. It asks the Spotlight index, and Spotlight leaves out whole classes of paths without saying so. Below is how mdfind's three query styles behave, which of my test files it missed and why, what it did to real trees (5,542 Python files reduced to 88), and the quieter traps: exit codes, case rules, and two lines of log noise it writes to stderr on every name search. I also went through all 77 Stack Exchange questions with mdfind in the title.

What mdfind does, and the three ways to query it

The mdfind man page (dated June 10, 2004, still the one installed on macOS 26.4.1) says it "consults the central metadata store". That store is the same index the Spotlight menu uses. There are three ways to ask it something:

# 1. file name only: case-insensitive substring match
mdfind -name invoice

# 2. a plain word: matched against names, text content and other attributes,
#    the way the Spotlight menu would interpret it
mdfind invoice

# 3. a raw metadata query: exact attribute, your own wildcards and flags
mdfind "kMDItemFSName == '*.pdf'c"
mdfind "kMDItemCFBundleIdentifier == 'com.apple.Terminal'"

# scope, count, and NUL-separated output for xargs -0
mdfind -onlyin ~/Projects -count -name invoice
mdfind -0 -name invoice | xargs -0 ls -l

The bundle ID query returned /System/Applications/Utilities/Terminal.app here, which is the most reliable thing mdfind does: finding apps and documents in places Spotlight is meant to cover. The raw query syntax is documented in Apple's archived File Metadata Query Expression Syntax page, including the c (case-insensitive) and d (diacritic-insensitive) modifiers.

8 of 21 test files never showed up

Each file below contained the line body ZQX1630Acontent here and had the token in its name. I checked at 10-second intervals for over a minute after creating them, then again six minutes later, after the other tests. The result didn't change.

Where the file was	mdfind -name found it
A normal folder under ~/work	Yes
Same folder, 10 more extensions: .md .py .json .log .sh .csv .html .swift .yaml and no extension	10 of 10 (the text inside was searchable too)
node_modules/pkg/	Yes
Five folders deep	Yes
A dotfile (.ZQX…) in that normal folder	No
Inside a dot-folder (.hidden/)	No
.git/objects/	No
~/.slot1630dot/ (dot-folder in home)	No
~/Library/Caches/	No
/tmp (really /private/tmp)	No
A folder named skip.noindex	No
Inside a bundle, Thing.app/Contents/	No

Four rules explain the misses. Anything whose name or any parent's name starts with a dot is skipped. Folders ending in .noindex are skipped, which is the trick I used in my mds_stores high CPU measurements to keep build output out of the index. Package contents (anything inside a .app or other bundle) aren't listed as separate files. And most of ~/Library and the system's temporary folders are excluded. Note what was indexed: node_modules, which has no dot, so it's searchable and also adds to the indexing load.

For new files in covered folders, the index is fast. Over five fresh files, -name found each one 1.70 to 2.06 seconds after it was written, and a content search 1.76 to 2.11 seconds after.

On real folders: find vs mdfind counts

The same rules applied to directories that already existed on this machine:

The Python row is the one that misleads people. My repos have one virtualenv in a .venv folder, and it held 5,454 of the 5,542 .py files. find ~/GitHub -name '.*' -prune -o -name '*.py' -print, which skips dot-folders, returned 88, the same number as mdfind. So mdfind's answer was internally consistent; it just answered a narrower question than the one I asked.

/opt/homebrew returned nothing at all, which matches "How do I get mdfind to look in /opt?" on Ask Different. The accepted workaround there is mdimport /opt. I tried mdimport on a 35-entry Homebrew folder, a dot-folder and a /tmp folder, and none of them were findable 10 seconds later. mdimport -t -d1 on one of the hidden files reported "29 attributes returned", so the importer can read the file, but the result didn't land in the index. I also don't know exactly which rule excludes /opt. It carries the hidden file flag, but when I ran chflags hidden on an indexed test folder, its file stayed searchable and a new file written inside it was indexed too.

On speed: find beat mdfind on every tree small enough to compare. find ~/GitHub took 0.030 seconds against mdfind's 0.075, and find walked all 257,239 files under ~/work in 0.85 seconds. mdfind's advantage is scope: mdfind -count "kMDItemFSName == '*.json'" counted 12,188 files across the whole indexed volume in 1.63 seconds without touching protected folders. On a Mac, a find over all of ~ can stall on privacy prompts, which I covered in Full Disk Access for Terminal. For a "does this exist anywhere" question, mdfind is the better tool. For a tree you control, find is faster and complete.

If you're thinking of locate instead: /var/db/locate.database doesn't exist on this machine and com.apple.locate isn't loaded, so locate has nothing to search until you enable and build its database yourself.

Name matching, case and wildcards

• -name is a case-insensitive substring match. -name zqx1630a returned all 13, -name 1630A_ext returned 10, and -name .py returned 105 files where the exact *.py query returned 88. The extra 17 were .pyc files.
• Raw queries are case-sensitive unless you add c. "kMDItemFSName == 'zqx1630a*'" returned 0; with c after the closing quote it returned 13. Without a *, the name must match exactly.
• Plain words already prefix-match. mdfind ZQX1630Ainne found the 10 files containing ZQX1630Ainner…, because the man page's -interpret example shows a word becoming search* cdw. Adding your own * made it worse: mdfind "ZQX1630Ainner*" returned 0. Wildcards belong in raw queries, as the 9,518-view wildcard question on Ask Different eventually concludes.

Two traps for scripts

Exit code 0 means nothing. A search with no matches exited 0. -onlyin /nonexistent also exited 0, with no output and no error message, so a typo in the scope looks the same as an empty result. Only a malformed query failed: "kMDItemFSName ==" printed Failed to create query and exited 1. In a script, test the output, or use -count and compare against 0:

[ -d "$dir" ] || { echo "no such dir: $dir" >&2; exit 1; }
n=$(mdfind -onlyin "$dir" -count -name "$name" 2>/dev/null)
[ "$n" -gt 0 ] || echo "not in the Spotlight index (may still exist on disk)"

stderr noise on every name search. Each -name or plain-word search here printed two lines like mdfind[79948:19898496] [UserQueryParser] Loading keywords and predicates for locale "ko_KR", followed by one for "ko". Setting LANG=en_US.UTF-8 didn't change the locale it reported, which follows the account's region setting. The Ask Different report from January 2025 shows the same lines for en_US after an upgrade to Sequoia. Raw kMDItem… queries and -literal printed nothing. The lines go to stderr, so 2>/dev/null removes them and your pipes are unaffected, but anything that captures both streams will log them.

One more for debugging: mdls is not proof that a file is indexed. It returned kMDItemFSName for the files in .hidden/ and skip.noindex/, which mdfind never found. mdls reads attributes from the file on request, so a file can have metadata and still be absent from the index.

What 77 Stack Exchange questions ask

I pulled every question with mdfind in the title from Stack Overflow (27), Ask Different (40), Super User (8) and Unix & Linux (2): 77 questions with 96,852 views between them. Sorting by title, 29 (51,256 views) are about building the query: wildcards, exact names, phrases, dates, case, excluding a folder. Another 16 (10,030 views) are "mdfind doesn't find X": files in /opt, in a virtualenv under a dot-folder (Super User 732571), in system and Library folders, symlinks, Notes, Mail. Most of those 16 match one of the four exclusion rules above. The rest of the 77 are scripting: spaces in paths, piping to xargs, AppleScript wrappers. If you pipe results into xargs, use -0 with xargs -0; my xargs on macOS post covers why the BSD version needs it.

The practical rule: use mdfind to ask "where on this Mac is the file named X" or "which app has bundle ID Y", and use find for anything inside dot-folders, /opt, /tmp, ~/Library or app bundles. If you rely on mdfind to audit backups the way my tmutil isexcluded audit did, remember that a missing result can just mean the path isn't indexed.

FAQ

Why doesn't mdfind find hidden files?

Spotlight doesn't index files whose name or parent folder name starts with a dot, so mdfind can't return them. On macOS 26.4.1 I also found nothing in .noindex folders, inside .app bundles, in ~/Library/Caches, /tmp or /opt/homebrew. Running mdimport on those paths didn't add them. Use find for those locations, for example find ~/.config -name '*.json'.

What is the difference between mdfind and find?

find walks the directory tree on disk and sees every file it has permission to read. mdfind queries the Spotlight index, so it's quick across a whole volume and can search file contents and metadata like bundle IDs, but it skips paths Spotlight doesn't index. In one test, find returned 5,542 .py files under ~/GitHub and mdfind returned 88, because 5,454 were inside a .venv folder.

How do I hide the UserQueryParser messages from mdfind?

The "[UserQueryParser] Loading keywords and predicates for locale" lines are written to stderr, so add 2>/dev/null to the mdfind command. They appear for -name and plain-word searches. Raw attribute queries such as mdfind "kMDItemFSName == '*.pdf'c" and queries run with -literal didn't print them on macOS 26.4.1.

Method: all tests ran on 2026-10-07 between 16:30 and 16:45 KST on a Mac mini M4 (Mac16,10, macOS 26.4.1 build 25E253), from a launchd-started job in the logged-in session. The account's region is Korean, which is why the stderr lines say ko_KR. The 21 test files were created by one script at 16:32:42 and checked with mdfind -name every 10 seconds, then rechecked later; the latency figures come from five more files polled every 0.2 seconds. The find vs mdfind counts used directories already on this machine, and find was not run over the whole home folder because of privacy-protected folders. The mdimport tests covered one Homebrew subfolder, one dot-folder and one /tmp folder, not all of /opt. The 77-question census is every question with mdfind in the title on the four Stack Exchange sites named, pulled through the Stack Exchange API today and bucketed by title. Search phrasings like "mdfind vs find" and "mdfind hidden files" come from our own Google autocomplete collection for mdfind on the same day.