How Spotlight indexes your files and why it rebuilds

Spotlight does not search your files. It searches a database it built earlier by reading them. When search stops returning things that plainly exist, the database has drifted from the disk. Apple's fix is to make Spotlight forget a location so it indexes it again.

That is the whole model. Everything else follows from it, including why the official repair looks backwards.

What the index holds

The file system knows where every file is and what it is called. It knows nothing about what is inside one.

Spotlight reads the contents and records what it finds there. Text from documents. Metadata from photos, including camera and date. Sender and subject from mail. Track and album from music. It writes all of that into a database sitting in a hidden folder at the top of every volume it indexes.

Two consequences matter.

A search for a word inside a PDF works, which no file system could answer. And a file that exists perfectly well can be invisible to search, because the index has not caught up or has lost the entry. The file is fine. The description of it is missing.

This is the distinction the whole subject turns on. Spotlight failing is a search problem rather than a storage one. Nothing is at risk while you fix it.

Where those files physically sit is a different subject, covered in how the Mac file system lays data on disk.

Check the cheap causes before rebuilding

A rebuild takes hours. Four things cost nothing and explain most failures.

The last row saves the most time. Mail search failing while everything else works points at Mail's own database rather than Spotlight.

Spotlight is not the only index on the machine

This is worth separating early, because it decides which repair applies.

Spotlight indexes the disk. Several applications keep their own index as well, describing only their own content. Those fail independently.

Rebuilding the wrong one costs hours and changes nothing. That is the most common way this goes wrong.

The Privacy list, which is also the repair

System Settings keeps a list of places Spotlight skips. In current macOS it is under Spotlight in the sidebar and the button is Search Privacy. On earlier releases the pane is called Siri and Spotlight and the button is Spotlight Privacy.

Its ordinary use is obvious. Add a folder and its contents stop appearing in search.

The part nobody expects is that this list is also Apple's documented repair tool. Adding a location discards its index. Removing it again starts a fresh one.

The rebuild Apple documents

Step three is the one people refuse to do, because adding your startup disk to a list of things not to search feels like the opposite of a fix. It is the fix. Apple's own page prescribes exactly this add and remove sequence.

Scope it as narrowly as the symptom allows. If only one folder is missing from results, add and remove that folder rather than the whole disk. Ten minutes instead of ten hours.

The Terminal route and when it earns its place

There is a command line equivalent and most guides lead with it. Apple's position is that Settings should be enough in almost every case. That is the right default.

Two commands are worth knowing anyway. mdutil -s / reports whether indexing is even enabled on a volume, which answers a question the interface does not. And sudo mdutil -E / discards the index for a volume and starts again.

Reach for those after Settings has failed rather than instead of trying it. A large share of the Terminal instructions circulating for this get the flag syntax wrong in ways that produce an error rather than a rebuild, which then reads as a deeper fault.

What a rebuild costs

More than the guides admit, which is why it belongs after the cheap checks rather than before them.

Time. Hours on a full disk, with no estimate shown anywhere.

Heat and battery. The indexing processes read every file on the volume. Fans run, a laptop gets warm and the battery drains at several times the usual rate.

Degraded search while it runs. Results stay partial until it finishes, so the machine looks worse before it looks better. People abandon it halfway.

Nothing at all to your files. The index derives from your files. Losing it costs the search results and not one byte of anything else.

Why it happens after an upgrade

The surge follows every major macOS release and the reasons are ordinary.

An upgrade rewrites large parts of the system, so Spotlight has a great deal to read again. A release can change the index format, which forces a full rebuild in place of an update. And the machine is busy with everything else an upgrade triggers at the same moment.

So poor search for a day or two after a major upgrade counts as expected rather than broken. The mistake is rebuilding on day one, which throws away the work already done and starts the same job over.

Give it a day of normal use before deciding anything is wrong.

What a rebuild does not fix

Spotlight refusing to open at all points at a keyboard shortcut or a system problem rather than an index. Results appearing but the wrong ones points at the Search Results categories. A drive that indexes forever and never finishes points at the drive rather than the index. Repeated rebuilding on failing hardware makes things worse.

One quirk is documented and catches people. A Time Machine backup disk keeps reporting that it is being indexed even after you exclude it, because Time Machine needs that indexing to work and nothing turns it off.