Spotlight problems

When Spotlight stops searching file contents

Updated 2026-07-31 · 5 min read

Content search depends on a plugin that knows how to read each format. When one is missing or a file has no text to read, Spotlight silently falls back to filenames and never tells you.

Check that it is really failing

Search for a phrase you know is inside a plain .txt file. Text files are handled by a built-in importer, so if that works, the machinery is fine and the problem is format specific.

From the Terminal, the definitive test:

mdfind "a phrase inside the document"

and to see exactly what macOS extracted from a specific file:

mdimport -d2 -t /path/to/file.pdf

That prints the metadata and text Spotlight has, which usually answers the question immediately.

The usual causes

The PDF is a scan. A photographed or scanned page is an image. There is no text to index until it has been through OCR. This is by far the most common case.

The app's importer is not installed. Content search for proprietary formats — older Office files, design tools, some note apps — depends on a plugin the app installs. Reinstall the app, or check /Library/Spotlight and ~/Library/Spotlight for its .mdimporter.

The file is in an excluded location. Content search obeys the same exclusions as everything else, so ~/Library and Privacy-listed folders return nothing.

The importer cache is stale. Rebuild it:

sudo mdimport -R

Force a single file to be re-read

mdimport /path/to/file

Useful after installing an app whose importer was missing when the files were first indexed.

Worth knowing

Filename search and content search are different problems with different costs. Everywhere deliberately does only the first — it does not read inside your files at all — because that is what makes it instant, and because Spotlight is genuinely good at content search once the importer situation is sorted out. Using both is a reasonable setup.

Common questions

Can Spotlight search inside scanned PDFs?

Only after OCR. Preview can add a text layer on some versions of macOS, and most PDF tools offer OCR.

What is an mdimporter?

A plugin that teaches Spotlight to read a file format. Apps install them into /Library/Spotlight or their own bundle.