How to Use the mdfind Command in macOS Terminal to Search Files with Spotlight Metadata

When searching for files in macOS Terminal, users accustomed to standard UNIX environments often default to the find command (e.g., find / -name "*.pdf"). However, because standard find executes a linear disk traversal scanning millions of directory inodes sequentially, searches across modern 2TB+ SSDs can take minutes and cause heavy disk I/O. macOS includes a lightning-fast command-line interface to the native Spotlight indexing engine called mdfind. By querying pre-indexed metadata stores, mdfind returns complex file searches across millions of documents in milliseconds.

Basic Syntax and Instant Filename Queries

The standard syntax for executing a search with mdfind is straightforward:

mdfind <query>

To locate every file containing the word “budget” in its filename or contents across your entire Mac:

mdfind budget

Results are streamed instantly to standard output with zero noticeable disk lag.

Restricting Searches to Specific Directories (-onlyin)

By default, mdfind queries the entire system index across all internal and connected external APFS drives. To constrain your search to a specific directory tree (such as your Documents or Projects folder), pass the -onlyin parameter:

mdfind -onlyin ~/Documents "Q4 Financials"
mdfind -onlyin /Volumes/WorkDrive "contract"

Querying Specific Spotlight Metadata Attributes

The true power of mdfind lies in querying discrete metadata attributes indexed by macOS (such as EXIF camera data, PDF authors, audio bitrates, or pixel dimensions). The syntax uses the -name flag or metadata attribute filters:

1. Matching Exact Filenames (-name)

mdfind -name "project_roadmap.pdf"

This bypasses full-text content searching and matches exclusively against the file’s name string.

2. Filtering by File Content Type (kMDItemContentType)

To find all JPEG images, PDF documents, or Xcode projects matching a query, filter by Apple Uniform Type Identifier (UTI):

mdfind 'kMDItemContentType == "com.adobe.pdf" && kMDItemTextContent == "NDA"'
mdfind 'kMDItemContentType == "public.jpeg" && kMDItemPixelWidth > 3000'

3. Searching by Modification Date (kMDItemContentModificationDate)

To isolate documents modified within the previous 24 hours:

mdfind 'kMDItemContentModificationDate >= "$time.today(-1)"'

Live Real-Time Monitoring with mdfind -live

System administrators and developers can monitor file system changes live in real time using the -live flag. The terminal prompt stays open and dynamically prints file paths the exact split-second matching files are created, modified, or saved:

mdfind -live -onlyin ~/Downloads "kMDItemFSSize > 100000000"

This command monitors your Downloads folder, alerting you immediately whenever a file larger than 100MB finishes downloading.

Inspecting Available Metadata Attributes with mdls

To discover which metadata keys are available for querying on any specific file format, pass the target file to the companion mdls (Metadata List) utility:

mdls sample_photo.jpg

The output reveals dozens of queryable keys—including kMDItemLatitude, kMDItemFocalLength, kMDItemCreator, and kMDItemKind—which you can immediately plug into mdfind queries.