How Spotlight Works on Mac

The Index: What It Is and Why It Exists

Searching a hard drive or SSD by reading every file in sequence would be unbearably slow. Spotlight solves this by building and maintaining an index — a pre-computed database of metadata and content that can be queried in milliseconds.

The index lives in a hidden folder called .Spotlight-V100 at the root of each indexed volume. This is why Spotlight results appear almost instantly: it's querying a database, not reading files.

The mds Daemon

mds (Metadata Server) is the background process that owns the Spotlight index. It runs continuously and is responsible for:

• Watching the filesystem for changes using the kernel's FSEvents API. When a file is created, modified, or deleted, macOS notifies mds immediately.
• Coordinating indexing work — the actual extraction is done by a companion process called mdworker, which mds spawns as needed.
• Maintaining index health — compacting, updating, and rebuilding index segments over time.

You can see mds in Activity Monitor. It normally uses minimal CPU. Sustained high CPU from mds usually means an active index rebuild is underway.

mdimporter Plugins

mds doesn't know how to extract content from every file format itself — that's done by mdimporter plugins. Each plugin is a small bundle that teaches mds how to read a specific file type and what metadata attributes to extract.

macOS ships with mdimporters for common formats: PDF, Word, Excel, JPEG, MP3, AAC, QuickTime, and many others. Third-party apps can install their own. Sketch, Final Cut Pro, Adobe apps, and most professional tools provide mdimporters so their files appear fully in Spotlight results.

If a file type has no mdimporter, Spotlight can still find it by name — it just won't index the content. This is why you can search for a .py file by name but not always search for text inside it.

What Spotlight Indexes

The index captures several layers of information:

• File system attributes: name, path, size, kind, date created, date modified, permissions
• Document content: text extracted from PDFs, Office documents, plain text files, source code, HTML, and more — via mdimporter
• EXIF/XMP metadata: for photos and videos: camera make/model, GPS coordinates, date taken, exposure settings, aperture, ISO
• Document metadata: author, title, word count, page count, application that created the file
• Audio metadata: artist, album, duration, sample rate, codec, bit depth
• macOS Tags: Finder color labels and tags

All of these attributes are stored as kMDItem* attributes in the index (for example, kMDItemFSName for file name, kMDItemGPSLatitude for photo latitude). Tools like mdfind and HoudahSpot query these attributes directly.

What Spotlight Does Not Index by Default

Understanding what's excluded is just as important as knowing what's included:

• External drives: not automatically indexed when connected. You need to verify indexing is enabled (mdutil -sa in Terminal, or check System Settings).
• Locations in Spotlight Privacy list: any folder or volume explicitly excluded in System Settings → System Settings… → Spotlight → Search Privacy.
• Folders with .metadata_never_index: a hidden marker file at the root of a folder instructs Spotlight not to index it. Some apps create these deliberately.
• Very recently created or modified files: there's a delay between a file change and the index update. New files typically appear in results within a minute, but this isn't instant.

Finder Search vs. the Spotlight Window

Both query the same index, but present results differently:

• Spotlight window (Cmd+Space): returns results from multiple categories (files, apps, web, Siri, definitions). Filters out ~/Library and system folders from the default view. Prioritizes relevance and recency.
• Finder search (Cmd+F): scopes to the current folder by default. Presents results as a file list with full Finder context. Allows adding filter criteria through the UI. Files only — no mixed-category results.

Neither interface exposes the full depth of the index. Spotlight filters for a clean, general-purpose result set. Finder is designed for browsing rather than deep query building.

How Query Tools Use the Index

Any app can query the Spotlight index using Apple's MDQuery API or the mdfind command-line tool. This includes:

• Alfred, Raycast, LaunchBar: query the index for file name matches in their launcher flows
• HoudahSpot: builds MDQuery expressions from the visual query builder and returns full file results with metadata columns
• mdfind: command-line interface to the same API — useful for scripting or debugging

Because they all read the same index, the data available to any of them is identical. What differs is how much of it each tool exposes in its UI, and how queries are constructed.

For more on how HoudahSpot specifically extends Spotlight's capabilities, see HoudahSpot and Spotlight: Better Together. If Spotlight is failing to find files you know exist, see Why Spotlight Can't Find Your Files.