Standard Unix search commands like find crawl filesystem directory trees sector by sector, which can take several minutes when searching across millions of files on high-capacity SSDs. macOS features an indexing engine known as Spotlight, maintained by the metadata server (mds). The built-in command-line utilities mdls (Metadata List) and mdfind (Metadata Find) query this real-time indexed database directly, delivering instantaneous search results based on deep file attributes such as camera EXIF data, audio sample rates, video codecs, and document authors.
Inspecting File Metadata with mdls
Every file on an APFS or HFS+ volume indexed by Spotlight contains an array of key-value metadata attributes prefixed with kMDItem. To view all metadata associated with any file:
mdls sample_photo.jpgOutput displays hundreds of granular properties, including ISO speed ratings, lens models, color space profiles, geographical GPS coordinates, and pixel dimensions. To query a specific metadata key:
# Get exact image dimensions
mdls -name kMDItemPixelWidth -name kMDItemPixelHeight sample_photo.jpg
# Inspect the exact PDF creation software
mdls -name kMDItemCreator report.pdf| Spotlight Metadata Key | Content Type | Example Stored Value |
|---|---|---|
kMDItemContentType |
Uniform Type Identifier (UTI) | public.jpeg, com.adobe.pdf, public.shell-script |
kMDItemFSSize |
Physical File Size (Bytes) | 10485760 (10 MB) |
kMDItemDurationSeconds |
Media Playback Duration | 182.4 (seconds) |
kMDItemAuthors |
Document Author Metadata | ["Jane Doe", "Engineering Team"] |
Executing Instant Searches with mdfind
The mdfind command queries the local Spotlight index, returning matched file paths immediately without crawling the directory tree.
# Basic full-text search matching contents and filenames
mdfind "Quarterly Financial Analysis"
# Restrict the search scope strictly to a specific folder
mdfind -onlyin ~/Documents "Project Roadmap"Constructing Advanced Attribute Queries
The true power of mdfind lies in its boolean predicate queries using the -interpret or raw metadata query syntax:
# Find all PNG images wider than 3840 pixels (4K UHD)
mdfind "kMDItemContentType == 'public.png' && kMDItemPixelWidth >= 3840"
# Find all audio tracks with an audio bit rate over 320 kbps
mdfind "kMDItemAudioBitRate > 320000"
# Locate all documents modified within the last 24 hours
mdfind "kMDItemFSContentChangeDate >= $time.now(-86400)"Managing and Rebuilding the Spotlight Index with mdutil
If mdfind fails to return recently created files or reports corrupt metadata, manage the index daemon using mdutil:
# Check indexing status on the root volume
mdutil -s /
# Erase and rebuild the Spotlight index on the boot disk
sudo mdutil -E /Mastering mdls and mdfind allows macOS power users to build high-speed shell scripts, automate document archiving, and locate project assets instantly.