mdfind: Run Spotlight Searches From Terminal on Mac

The classic find command crawls the disk folder by folder, which can take minutes. mdfind asks Spotlight's already-built index instead, so results come back in a fraction of a second — and because it's Spotlight, it searches file contents and metadata, not just names. It is the fastest search tool on your Mac, and it's already installed.

The two searches you'll run most

A bare query searches everything Spotlight knows — names, contents, metadata:

# every file mentioning the word, anywhere indexed
mdfind invoice

# match on the file name only
mdfind -name budget.xlsx

The difference matters: mdfind report returns PDFs containing the word "report" in their text; mdfind -name report only returns files with "report" in the filename. Both are read-only — mdfind never changes anything, so there is nothing to undo.

Scope it to one folder

Whole-Mac results are noisy. -onlyin restricts the search to a directory tree, and -count tells you how big the result set is before you dump it to the screen:

# only look inside Documents
mdfind -onlyin ~/Documents contract

# how many matches, without listing them
mdfind -count -onlyin ~/Downloads .dmg

Pipe into other tools like any Unix command: mdfind -onlyin ~/Desktop invoice | head -5 shows the first five hits.

Metadata queries: the real power

Every indexed file carries Spotlight attributes — pixel dimensions, authors, content type, dates. Query them directly with the attribute syntax:

# images taller than 3000 pixels
mdfind 'kMDItemPixelHeight > 3000'

# files bigger than 1 GB
mdfind 'kMDItemFSSize > 1000000000'

# everything you opened via a given app or type
mdfind "kMDItemContentType == 'com.adobe.pdf'"

Combine clauses with &&, and mix in -onlyin to keep it scoped. Quoting matters: wrap the whole query in quotes so the shell doesn't eat the > character.

How do you know what attributes exist? Ask a file that has them with mdls, mdfind's companion:

# list every Spotlight attribute on a file
mdls photo.jpg

# just one attribute
mdls -name kMDItemPixelHeight photo.jpg

Whatever mdls shows on a real file, you can search with mdfind. That pair — inspect with mdls, hunt with mdfind — replaces a surprising amount of scripting.

When mdfind finds nothing

• The location isn't indexed. Folders excluded in System Settings → Spotlight (the privacy/exclusions list at the bottom of the pane) are invisible to mdfind, as are most external drives that have indexing turned off.
• The index is stale or damaged. If Spotlight itself is returning odd results, the index may need rebuilding — mdfind inherits whatever state it's in.
• You need unindexed search. For system directories and anything Spotlight skips, fall back to find — slower, but it reads the disk directly.

One last flag worth knowing: mdfind -live query keeps running and updates the match count as files change — a lightweight way to watch for a download or export appearing.

Two recipes to keep

# everything changed in the last week, in one folder
mdfind -onlyin ~/Documents 'kMDItemFSContentChangeDate >= $time.today(-7)'

# open the first match straight from the search
open "$(mdfind -name 'budget.xlsx' | head -1)"

The $time keyword is part of Spotlight's query language — $time.today(-7) means "seven days ago," and $time.now and $time.this_month work the same way. The second recipe chains mdfind into open, which is the pattern for acting on results: swap open for ls -l, cp, or anything else that takes a path.

Keep the index healthy

All of this is only as good as Spotlight's index. If results look wrong in Terminal and in the Spotlight menu alike, see our guide to rebuilding the Spotlight index.