Search on a Mac, and where Spotlight stops

Spotlight search on a Mac opens with Command-Space bar. Type a few letters, press Return to open the top match, hold Command to see where a file lives, and press Space bar to preview it. On macOS 27, the release Apple's Mac User Guide currently documents, Spotlight also has four Browse Modes on Command-1 to Command-4, a kind: keyword syntax, and quick keys for actions. Most people searching for "OS X Spotlight search" either want those shortcuts or want to know why Spotlight did not find a file that definitely exists. This guide covers both, using Apple's current documentation (checked 8 October 2026) and the command line tools that ship with macOS 27.0.1.

The shortcuts that cover most searches

The name "OS X" was retired years ago, but Spotlight's basic behaviour has stayed close to what long-time users remember. The current Apple guide lists these controls.

Action	Keys
Open Spotlight	Command-Space bar
Open the selected result	Return, or double-click
Recall the previous search	Up Arrow
Show the file in Finder	Select the result and hold Command
Preview without opening	Space bar (Quick Look)
Reveal Quick Actions for a result	Tab

Two behaviours are newer. The Spotlight window can be moved and resized by dragging it, and pressing Tab on a selected result shows actions that depend on what is selected, such as sharing a file or acting on a contact.

Spotlight also answers small questions directly. Apple's examples include math such as 120 × 1.08, unit and currency conversions such as 5 miles in km, and word definitions without opening Dictionary. With Apple Intelligence and the Siri AI beta switched on, Spotlight becomes the place to ask Siri a question as well. That feature carries conditions: Apple's page states that Siri AI is in beta on macOS 27, available in English to start, and subject to usage limits.

For finding files specifically, the most useful habit is holding Command on a result, which Apple describes as the way to locate the file in Finder. When the same name exists in several projects, that is the quickest way to tell them apart before opening the wrong copy.

Browse Modes and keywords that narrow results

The default Spotlight result list mixes apps, files, mail, settings and web suggestions. When the target is a file, that mix is the main source of noise. Apple's "Narrow your search results in Spotlight" page describes four Browse Modes.

1. Applications: Command-1
2. Files: Command-2
3. Actions: Command-3, which searches actions and shortcuts
4. Clipboard: Command-4, which searches clipboard history

Pressing Command-2 before typing is the single change that makes Spotlight behave most like a file search.

Beyond modes, there are three ways to filter.

By location. Type a location such as iCloud Drive, press Tab, then type the file name. The search is limited to that place.

By kind with a slash. Type a slash followed by a type, for example /PDF, then press Return.

By keyword. Put kind: at the start of the query. Apple's example is kind:images New York City. The documented keywords include kind:folder, kind:pdf, kind:image, kind:movie, kind:presentation, kind:email and kind:app, each with a plural form.

Apple's page also lists other keywords that take a colon: from, to, author, with, by, tag, title, name, keyword and contains. So name:invoice restricts matching to file names, and tag:urgent returns items carrying that Finder tag.

Quotation marks matter too. Apple's troubleshooting page explains that a phrase in quotes, such as "trip to Paris", matches the exact phrase, while the same words without quotes match items containing them in any order.

Why Spotlight misses files that exist

When a search comes back empty for a file that is definitely on the disk, the cause is almost always one of five things. Apple's page "If searching your Mac returns unexpected results" covers most of them.

If you began your search in Spotlight, the search results can include email, calendar events, information from other apps, and more. If you began your search in a Finder window, the search results include only files and folders on the internal disk. Source: support.apple.com

1. The category is switched off. In System Settings, under Spotlight, the "Search results" list has a checkbox per category. An unchecked category never appears in results.

2. The folder is excluded. In System Settings > Spotlight, the Search Privacy button in the lower right opens a list of excluded folders and disks. A project folder dropped in there months ago, perhaps to stop indexing a large build directory, silently disappears from every search.

3. The file is inside an archive. Spotlight does not look inside zip files or disk images. Apple's advice is to open the archive and search again.

4. Indexing has not finished. Spotlight relies on a local index that, according to Apple, never leaves the device. It is rebuilt after setup, after a macOS update, and as data changes. While it runs, an indexing progress indicator appears at the top of the Spotlight window.

5. Indexing is off for the volume. This one is easy to miss. On the Mac used to prepare this guide, running mdutil -s / on 8 October 2026 returned "Indexing disabled." for the startup volume. On a volume in that state, Spotlight file search cannot return files from it at all, however well the query is written.

Checking these five takes a couple of minutes and settles most "Spotlight is broken" complaints.

Side effects of excluding folders

Search Privacy is also the setting people reach for when indexing slows the machine down, and Apple's page on it lists two consequences worth knowing before adding anything. First, if certain files and folders are excluded, the Mac may stop notifying you about updates for some apps; excluding the entire internal disk means no update notifications at all. Second, a Time Machine backup disk cannot really be excluded. Adding it to the list still leaves messages that Spotlight is indexing it, because Time Machine needs that index to work. Spotlight does, however, leave out items on the backup disk that are not part of a Time Machine backup.

The safer pattern is to exclude only folders that are large, regenerated and never searched by hand, such as dependency or build output folders, and to leave document and project folders in the index. Files that were deleted or overwritten can still be searched for inside Time Machine, which Apple's troubleshooting page points to as the route for older versions.

Finder search and Spotlight are related but different

Pressing Command-F in a Finder window opens Finder search. It uses the same index, but Apple's documentation is explicit that Finder search returns only files and folders, while Spotlight can also return mail, events and app content.

Finder search has two strengths Spotlight lacks. First, it can be scoped to the current folder: after typing, choose the folder's name instead of "This Mac" in the bar below the search field. Second, its filter rows (the plus button) let you combine conditions such as Kind is PDF and Last modified date is within the last 7 days, and the whole search can be saved as a Smart Folder that updates by itself.

The trade-off is speed of entry. Spotlight is one shortcut away from anywhere. Finder search requires a window, a scope choice and often a filter row. A practical split looks like this:

Situation	Better tool
Opening a known file or app	Spotlight
Finding a file whose name is half remembered	Spotlight with Command-2 or name:
All PDFs changed this week inside one project	Finder search with filters
A search you run every week	Smart Folder
Hidden files, build output, exact path patterns	Terminal

Both are only as good as the index behind them. If the index is missing or excludes a folder, Finder search fails in exactly the same way.

Searching from the terminal: mdfind and find

Two command line tools cover what Spotlight's window does not. Both are built into macOS, and the options below come from the manual pages on macOS 27.0.1.

mdfind queries the same Spotlight index from a shell.

mdfind -onlyin ~/Documents/Project "quarterly report"
mdfind -name invoice
mdfind -count "kind:pdf"
mdfind -live -name draft

-onlyin limits the search to one directory, -name matches file names only, -count prints just the number of matches, and -live keeps running and updates as files change. Because it reads the index, mdfind is fast and also inherits every gap described above.

mdutil shows and manages the index. mdutil -s / displays the indexing status of a volume, -i on or -i off turns indexing on or off, and -E erases and rebuilds the local store. Rebuilding is the step people take when search results look stale, and on a full disk it is not instant.

find does not use an index at all. It walks the folder tree every time.

find ~/Documents/Project -name "*.md" -mtime -7

That command lists Markdown files changed in the last seven days, including in folders Spotlight has excluded, and in hidden directories. It is slower on large trees but never misses a file because of indexing state. When Spotlight and mdfind both come back empty and the file must exist, find is the tool that settles the question.

The friction in practice is not the commands. It is getting the terminal into the right folder. Typing a long path, or dragging a folder from Finder into the terminal window to paste its path, happens dozens of times a day for people who live in both. A file manager with a built-in terminal removes that step, since the terminal follows whichever folder is open; the features page describes one such setup.

Deciding where to search from

The right search tool depends on what is being searched and how often.

If the files are documents and the search happens a few times a day, Spotlight with Command-2 and kind: keywords is enough. Spend five minutes on System Settings > Spotlight to confirm that Documents and the main project folders are not in Search Privacy and that the Documents category is checked.

If the same filtered search repeats every week, build it once in Finder and save it as a Smart Folder. It stays current without anyone remembering the filter.

If the work involves code, build output, hidden folders or AI agents writing files in the background, the index will lag behind or exclude things on purpose. Search from the terminal with find or rg, and keep the terminal close to the folders being searched. Some file managers also offer saved searches in the sidebar, which brings the Smart Folder idea into the same window as the terminal. A comparison of how these tools divide the work is on the compare page.

Whichever route fits, the order of checks stays the same: is the volume indexed, is the folder excluded, is the category on, and is the file inside an archive.

What to change first

Run mdutil -s / in Terminal and open System Settings > Spotlight > Search Privacy. Those two checks explain most missing results. If searching and then acting on files in a terminal is a daily loop, Atriens keeps the folder, its terminal and saved searches in one window.