Spotlight Not Working on a Mac: Check This Before Rebuilding the Index

When Spotlight stops finding things, the usual advice is to rebuild the index. That works often enough to keep getting repeated, and it is also the most expensive thing you can do — a full rebuild rescans every file on the volume and can take hours. Before spending that, it is worth finding out whether the index is the problem at all.

Three commands answer that, and all three are read-only. They were run on macOS 26.5.2. The rebuild itself is described from its documented behaviour rather than executed here, for the same reason you should think twice about it.

Is indexing even turned on?

mdutil manages the indexes; -s prints status without changing anything:

$ mdutil -s /
/:
	Indexing enabled. 

One volume at a time is rarely the whole picture though. -a covers every store on every mounted volume, and that is where the answer usually turns up:

$ mdutil -s -a
/:
	Indexing enabled.
/System/Volumes/Data:
	Indexing enabled.
/System/Volumes/Preboot:
	Indexing enabled.
/Users/osxhub/VMShare:
	Indexing and searching disabled.
/Volumes/Installer:
	Indexing disabled.

The user name and two volume names are replaced above; the statuses are as printed. Two of these five are not indexed, and neither was ever configured by hand — mounted disk images and some virtualisation tools arrive with indexing off. If the files you cannot find live on a volume like that, no amount of rebuilding the main index will help, because that volume was never in it.

Note the two different wordings. “Indexing disabled” is the ordinary off state, turned back on with sudo mdutil -i on /Volumes/Name. “Indexing and searching disabled” is what mdutil -d produces, and its own usage text says it is re-enabled with -i on as well.

Ask the index directly, without the UI

This is the check that saves the most wasted effort. mdfind queries the same index the Spotlight window uses, with none of the interface in between:

$ mdfind -count "kMDItemFSName == 'Calculator.app'"
1

$ mdfind -onlyin ~/Documents "quarterly"

The split it gives you is clean. If mdfind returns your file and the Spotlight window does not, the index is fine and the problem is above it — search settings, a result category switched off, or the Spotlight window filtering by type. If mdfind returns nothing either, the file genuinely is not in the index and the earlier status output tells you why.

You can also ask about one specific file. mdls prints the metadata Spotlight holds for it:

$ mdls -name kMDItemContentType -name kMDItemFSName /System/Applications/Calculator.app
kMDItemContentType = "com.apple.application-bundle"
kMDItemFSName      = "Calculator.app"

Values coming back means that file is indexed. (null) across the board means it is not, which narrows the question from “Spotlight is broken” to “this one file or folder is not being picked up” — a much smaller problem, usually an exclusion or a file type with no importer.

Is it indexing right now?

Search results being incomplete right after a migration, a large copy, or a macOS update is normal: the index is still being built. The processes doing it are visible:

$ ps -Ao pid,%cpu,comm | grep -E "[m]ds|[m]dworker"
  549   0.0 .../Support/mds
  844   0.0 .../Support/mds_stores
70726   0.0 .../Support/mdworker_shared

Paths are truncated for width; they all live under Metadata.framework. mds is the server and is always running. What tells you the state is the CPU column: at 0.0 like this, nothing is being indexed. Several mdworker processes each burning real CPU means indexing is underway, and the right move is to leave it alone for an hour rather than to restart anything.

Indexing also needs somewhere to write. On a volume that is nearly full it can stall or fail quietly, so if the Mac is short of space, clear that first and revisit Spotlight afterwards.

Re-index one folder instead of the whole disk

Between “do nothing” and “erase the entire index” there is a step almost nobody reaches for. mdimport re-imports a specific path, and its usage spells out the two modes:

 -i            recursively import files at 'path', sending results to Spotlight index
 -t            spotlight server will test-import the specific file, but not send the
               results to the Spotlight index
 -d level      output information from test-import. Requires -t

So mdimport -i ~/Documents/Projects rebuilds the index entries for one folder in seconds, where mdutil -E would spend hours on the whole volume. If a single folder is the problem, try this first.

The test mode answers a different question — whether a file can be read at all:

$ mdimport -t -d1 /tmp/mdtest.txt
Imported '/private/tmp/mdtest.txt' of type 'public.plain-text' with plugIn /System/Library/Spotlight/RichText.mdimporter.
29 attributes returned

Those two lines name the detected type, the importer that handled it, and how many attributes came out. When a particular kind of file never appears in search results, this is where you find out why: no importer claims that type, so there is nothing to index beyond the file name. Installing the app that owns the format usually installs its importer with it.

The exclusion list nobody remembers adding to

System Settings has a Spotlight privacy list of folders and volumes that are never indexed. Things get added to it years earlier and forgotten, and by installers that add their own working directories. It is the single most common reason one specific folder is invisible while everything else searches fine.

The list lives under Spotlight’s settings in System Settings, and removing an entry makes that location eligible again — indexing then happens on its own schedule rather than instantly. This is also worth checking before any rebuild, because a rebuild does not clear exclusions and will leave you exactly where you started.

Rebuilding, and what it costs

If indexing is on, the volume is not excluded, and mdfind still cannot see files that are definitely there, the index is damaged and rebuilding is the answer. mdutil‘s own usage lists the relevant options verbatim:

	-i (on|off)    Turn indexing on or off.
	-d             Disable Spotlight activity for volume (re-enable using -i on).
	-E             Erase and rebuild index.
	-s             Print indexing status.
	-a             Apply command to all stores on all volumes.

sudo mdutil -E / erases the index and starts over. Expect heavy disk and CPU activity for a long time on a large volume, incomplete search results throughout, and a laptop that runs hot and loses battery faster while it works. There is no progress bar; the ps check above is how you tell it is still going.

Two things make that go better. Do it when you do not need the machine, because search will be unreliable until it finishes. And target the volume that is actually broken rather than adding -a — rebuilding every store on every volume takes far longer and fixes nothing extra.