Terminal commands for finding files on a Mac

To find a file from the Mac Terminal, there are three built-in commands, and they answer different questions. mdfind -name report asks the Spotlight index and returns in well under a second. find ~ -iname '*report*' walks the disk folder by folder and sees everything you have permission to read, but it is slow on a large home folder. locate report reads a prebuilt database that macOS does not build by default. If you only remember one rule: use mdfind first, and fall back to find when the file is hidden, inside ~/Library, in a temporary folder, or on a volume Spotlight does not index.

The rest of this guide gives the exact syntax for the searches people actually run (by name, by size, by date, by content), shows what each command misses, and includes timings measured on 9 October 2026 on a Mac running macOS 27.0.1.

The three commands side by side

Command Where the answer comes from Speed on a full home folder Sees hidden files and ~/Library Ready out of the box
mdfind Spotlight index Under a second Mostly no Yes
find Reads the disk live Minutes on a large home folder Yes Yes
locate Weekly database file Under a second Yes, if built No, the job is disabled

The speed column comes from a direct comparison. On the Mac used for this check, searching the home folder for files larger than 1 GiB took find about 417 seconds and returned 794 files. The equivalent Spotlight query, mdfind -onlyin ~ 'kMDItemFSSize > 1073741824', returned in 0.34 seconds with 450 files. The 344-file gap is the important number. Spotlight was fast because it skipped places it does not index, such as app containers and virtual machine images.

The same pattern shows up with small files. A search for SQLite databases under ~/Library returned 0 results from mdfind and 1,596 from find. A search with mdfind -name .zshrc found the system copies in /private/etc but not the one in the home folder, because dot files are not indexed.

So the choice is not about which command is better. It is about whether the file you want lives somewhere Spotlight looks.

find: the command that sees everything

find takes a starting folder and a set of tests, then prints every path that passes. The reference for the macOS version is the find page on SS64, which follows the BSD manual installed on the Mac (man find).

The searches most people need:

find ~ -iname '*invoice*'  # by name, case-insensitive, anywhere under the home folder

find ~/Downloads -maxdepth 1 -type f -iname '*.pdf'  # by name, only files (no folders), only one level deep

find ~/Documents -type f -mtime -2  # changed in the last 2 days

find ~/Documents -type f -newermt '2026-10-01'  # changed since a specific date

find ~ -type f -size +500M  # larger than 500 MB

Three details catch people out.

Case matters with -name. In a test folder holding Report.PDF and report-final.pdf, find . -name '*.pdf' returned only the second file. -iname returned both. Most Mac volumes are case-insensitive, so it is easy to forget that find patterns are not.

Quote the pattern. Without quotes, the shell expands *.pdf against the current folder before find ever sees it. That produces either a confusing error or a search for one specific name.

Permission errors flood the output. Running find ~ touches protected folders such as Mail and Safari data and prints "Operation not permitted" for each. Add 2>/dev/null to discard those lines, or give Terminal Full Disk Access in System Settings if you really need those folders searched.

The starting folder is the biggest lever on speed. The 417-second search above started at the home folder, which on that Mac includes app containers, caches and a virtual machine disk. The same size test started at ~/Documents, a folder of about 1,900 files there, finished in 0.11 seconds. Before reaching for a faster tool, narrow the starting point to the folder where the file most likely lives, and widen it only when that search comes back empty.

The size suffixes k, M, G, T and P are supported by the macOS find, according to its manual page. A leading + means larger than, a leading - means smaller than.

mdfind: Spotlight from the command line

mdfind sends a query to the same index that powers Spotlight in the menu bar. Its own help text lists the options: -name to match file names only, -onlyin to limit the search to a folder, -count to print just the number of matches, -live to keep the query open and print new matches as they appear, and -0 to separate results with a null character for safe piping. The mdfind page on SS64 lists the metadata attributes you can query.

mdfind -name budget  # file name contains "budget", anywhere indexed

mdfind -onlyin ~/Documents -name budget  # only inside one folder

mdfind -onlyin ~/Documents "quarterly forecast"  # any indexed file containing the phrase in its text

mdfind "kMDItemContentType == 'com.adobe.pdf' && kMDItemFSSize > 100000000"  # PDFs larger than 100 MB

mdfind -count -onlyin ~ 'kMDItemFSSize > 1073741824'  # just count matches

The content search is the part find cannot match without extra tools. Spotlight has already read the text of PDFs, Pages documents and many other formats, so mdfind can return a document by a phrase inside it.

To check whether indexing is on, run mdutil -s /System/Volumes/Data. On current macOS, mdutil -s / reports the read-only system volume, where indexing shows as disabled. That message does not mean Spotlight is off for your files.

Things mdfind will not show: dot files, most of ~/Library, /tmp and other temporary folders, files created in the last few seconds before the index catches up, and external drives that have been excluded in Spotlight settings. If the file you are after fits one of those, go straight to find.

locate: fast, but only after you build it

locate reads a single database file at /var/db/locate.database and prints every path that contains the text you give it. It is very fast because it never touches the disk being searched.

The catch is that macOS ships the job that builds the database switched off. The launch daemon definition at /System/Library/LaunchDaemons/com.apple.locate.plist has Disabled set to true. When enabled, it is scheduled to run once a week, on Saturday at 03:15. On the Mac used for this check, the database file was dated February 2025, so any file created since then would be invisible to locate.

The locate page on SS64 covers the search options. The ones used most are -i for case-insensitive matching, -l to stop after a given number of results, and -c to print only a count. To switch the weekly job on, load the same launch daemon file named above:

sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.locate.plist

To rebuild immediately rather than wait for Saturday, run sudo /usr/libexec/locate.updatedb. Expect it to take several minutes, since it walks the whole disk the way find does.

Whether this is worth doing depends on how you search. If you mostly look for files you created in the last few days, a weekly database will often be stale. If you look for configuration files and source trees that rarely change, locate fills the gap that Spotlight leaves.

Combining tests and skipping folders

Real searches usually combine conditions: a PDF or a text file, changed this month, not inside a dependency folder. find handles this with operators, and the syntax is the part most people look up every time.

find ~/Documents -type f \( -iname '*.pdf' -o -iname '*.txt' \)  # PDF or TXT, case-insensitive

find . \( -name node_modules -prune \) -o -iname '*report*' -print  # skip node_modules entirely, then match by name

find ~ -type f -size +100M -mtime +180 2>/dev/null  # larger than 100 MB and not touched for 180 days

Tests written one after another are joined by an implicit AND. -o means OR, and it binds more loosely than AND, which is why the parentheses are needed. They must be escaped with a backslash, or the shell will try to interpret them.

The -prune pattern is worth learning once. It tells find not to descend into a folder at all, which is much faster than descending and then filtering the results. In a test folder that contained a node_modules subfolder with its own report.js, the pruned command returned only the three report files outside it. The trailing -print matters: without it, find also prints the pruned folder name itself.

When a search becomes part of the routine, save it as a shell function in ~/.zshrc rather than retyping it:

ff() { find . -iname "*$1*" 2>/dev/null; }

After reloading the shell, ff invoice searches the current folder and everything below it, with permission noise removed.

Spotlight queries the Finder search bar cannot type

mdfind accepts raw metadata queries, and some of them answer questions that are awkward in the Finder search field. A few that returned results on the Mac used for this check:

mdfind "kMDItemUserTags == '*'"  # files that carry any Finder tag

mdfind 'kMDItemLastUsedDate >= $time.today(-7)'  # files opened in the last 7 days

mdfind "kMDItemWhereFroms == '*'"  # files that record where they were downloaded from

On that machine the three queries matched 610, 249 and 5,994 files respectively. The last one is useful for cleaning a Downloads folder, because mdls -name kMDItemWhereFroms <file> then shows the exact web address each file came from. That is often the fastest way to tell an invoice from a duplicate installer when the file names are meaningless.

Note the single quotes around the second query. Inside double quotes, the shell would try to expand $time as a variable and the query would silently change.

Searching inside files with grep

When the question is "which file contains this text" and Spotlight does not index the folder, grep does the job.

grep -rl "API_KEY" .  # list files under the current folder that contain the text

grep -rli --include='*.ts' "api_key" .  # same, but only in .ts files, ignoring case

grep -rn "TODO" src/  # show the matching lines with line numbers

-r recurses, -l prints file names only, -n adds line numbers, -i ignores case. For large source trees, a third-party tool such as ripgrep is faster and skips files listed in .gitignore by default. That default is helpful in code and surprising elsewhere, so it is worth knowing when results seem to be missing.

Doing something with the results

Finding the file is usually step one. The next step is opening it, moving it, or acting on every match.

open "$(mdfind -name budget-2026 | head -1)"  # open the first match in its default app

open -R "$(mdfind -name budget-2026 | head -1)"  # reveal it in a Finder window

find ~/Downloads -iname '*.dmg' -print0 | xargs -0 -I{} mv {} ~/Archive/  # move every match safely, even with spaces in names

find . -name '*.log' -exec gzip {} +  # run a command once on all matches

Use -print0 with xargs -0 (or mdfind -0 with xargs -0) whenever paths may contain spaces, which on a Mac is most of the time. File names like my report.txt split into two arguments otherwise.

Before running anything destructive, run the same find command without the action and read the list. find also has a -delete action, but it acts immediately and does not use the Trash.

Where the time actually goes

The commands above take seconds to type. What costs time in practice is the switching around them: searching in Terminal, copying a path, switching to Finder to look at the file, switching back to run the next command. With an AI agent running in the terminal, the loop gets longer, because the agent works in one folder while you check its output in another window.

Two small habits reduce that loop. open -R reveals a result in Finder from Terminal. In the other direction, dragging a file from a Finder window into Terminal pastes its full path at the cursor. A third approach is a file manager with a built-in terminal, where the terminal follows the folder you have open. The features page shows how that layout works, and the comparison with other file managers sets out where it fits next to tools such as Obsidian and Cursor.

What to change first

Make mdfind -name your default, and add find ~ -iname '*text*' 2>/dev/null as the fallback for hidden files and ~/Library. Turn on locate only if you regularly search folders Spotlight skips. If the bottleneck is switching between Terminal and Finder rather than the search itself, see how Atriens keeps the folder and its terminal in one window.

Frequently asked questions

Why does mdfind return nothing for a file that definitely exists?

The file is probably in a place Spotlight does not index, such as a hidden folder, ~/Library, /tmp, or an excluded drive. It may also have been created a moment ago. Run find on the folder you expect it to be in to confirm, then check indexing with mdutil -s /System/Volumes/Data.

How do I search for a file by name without caring about upper and lower case?

Use find with -iname instead of -name, for example find ~ -iname '*invoice*'. mdfind -name already ignores case. Always quote the pattern so the shell does not expand the asterisk first.

Why does locate say the database does not exist or return old results?

macOS ships the weekly job that builds the locate database disabled. Load it with sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.locate.plist, then run sudo /usr/libexec/locate.updatedb once to build it straight away.

How do I stop find from printing "Operation not permitted" lines?

Add 2>/dev/null to the end of the command to discard error messages. If you need those protected folders included in the search, give Terminal Full Disk Access under Privacy and Security in System Settings, then run the search again.

Back to all posts