Syntax mdfind [-live] [-count] [-onlyin directory] query Key query A string or query expression. -0 Print an ASCII NUL character after each result path. This is useful when used in conjunction with xargs -0. -live Causes the mdfind command to provide live-updates to the number of files matching the query. When an update causes the query results to change the number of matches is updated. The find can be cancelled by typing ctrl-C. -count Output the total number of matches, instead of the path to the matching items. -onlyin dir Limit the scope of the search to the directory specified. -literal Force the provided query string to be taken as a literal query string, without interpretation. -interpret Force the provided query string to be interpreted as if the user had typed the string into the Spotlight menu. For example, the string "search" would produce the following query string: (* = search* cdw || kMDItemTextContent = search* cdw)
These can be included in the query expression to limit the type of documents returned:
Applications kind:application, kind:applications, kind:app
Audio/Music kind:audio, kind:music
Bookmarks kind:bookmark, kind:bookmarks
Contacts kind:contact, kind:contacts
Email kind:email, kind:emails, kind:mail message, kind:mail messages
Folders kind:folder, kind:folders
Fonts kind:font, kind:fonts
iCal Events kind:event, kind:events
iCal To Dos kind:todo, kind:todos, kind:to do, kind:to dos
Images kind:image, kind:images
Movies kind:movie, kind:movies
PDF kind:pdf, kind:pdfs
Preferences kind:system preferences, kind:preferences
Presentations kind:presentations, kind:presentation
These can be included in the query expression to limit the age of documents returned:
date:this week .this_week()
date:this month .this_month()
date:this year .this_year()
date:next month .next_month()
date:next week .next_week()
date:next year .next_year()
By default mdfind will AND together elements of the query string.
| (OR) To return items that match either word, use the pipe character: stringA|stringB
- (NOT) To exclude documents that match a string -string
!= “not equal”
< and > “less” or “more than”
<= and >= “less than or equal” or “more than or equal”
InRange(attributeName,minValue,maxValue) Numeric values within the range of minValue to maxValue in the specified attribute.
Whitespace is significant when building a query, use parentheses () to create groups.
Characters such as “ and ‘ in the value string should be escaped using the \ character
Modifier Description c The comparison is case insensitive. d The comparison is insensitive to diacritical marks.
kMDItemAuthors ==[c] "Steve"
To get a list of the available attributes for use in constructing queries, see mdimport(1), particularly the -X switch. Not all files are indexed by spotlight and not all file attributes are present on all files, image files, iCal files and music files all support different attributes.
Returns all files with any metadata attribute value matching the string "image":
$ mdfind image
Return all files that contain "Len Deighton" in the kMDItemAuthor metadata attribute:
$ mdfind "kMDItemAuthor = '*Len Deighton*'"
Return all files with any metadata attribute value matching the string "skateboard". The find continues to run after gathering the initial results, providing a count of the number of files that match the query.
$ mdfind -live skateboard
Return all Microsoft.Word document files:
$ mdfind "kMDItemContentType = 'com.microsoft.word.doc'"
Return files where the composer name includes 'Eno' (non case sensitive search):
$ mdfind 'kMDItemComposer = "*ENO*"c'
Return all image files matching the words 'maude' and 'paris':
$ mdfind "kind:images maude paris"
Return all the files that have been tagged as 'Green':
$ mdfind "kMDItemUserTags = Green"
Return all the documents created with any version of Pixelmator:
$ mdfind "kMDItemCreator = Pixelmator*"
Return all image files last edited yesterday:
$ mdfind "kind:image date:yesterday"
Return all files in the users home folder (~) that have been modified in the last 3 days:
$ mdfind -onlyin ~ 'kMDItemFSContentChangeDate >= $time.today(-3)'
“The real voyage of discovery consists not in seeking new landscapes but in having new eyes” ~ Marcel Proust
Related macOS commands:
Spotlight Metadata Attributes - List of all the kDM* attributes (or just use mdls to list the attributes of a file).
mdls - List the Spotlight metadata attributes for a specified file.
mdutil - Manage Spotlight metadata store.
mdimport - Import file hierarchies into the Spotlight datastore.
find - Search for files that meet a desired criteria.