mdfind - macOS

Overview

mdfind is a powerful command-line tool on macOS used to perform rapid and comprehensive file searches across an entire file system or specified directories. It leverages the Spotlight indexing service to deliver exceptionally fast and accurate results, making it ideal for locating files by name, content, type, and other metadata attributes.

Syntax

mdfind [-help] [-name name] [-kind kind] [-attribute key value] [-mtime days] [-ctime days] [-atime days] [-size size] [-regex pattern] [-or expression1 expression2...] [-and expression1 expression2...] [-exclude exclude_expression] [-onlyfiles] [-depth level] [-multiprocess] [-local] [-onlyin directory]

Options/Flags

  • -help: Displays the help message.
  • -name name: Searches for files with the specified name.
  • -kind kind: Filters results by file type (e.g., file, directory).
  • -attribute key value: Matches files with specific metadata attributes (e.g., kMDItemKindText for text files).
  • -mtime days: Finds files modified in the last days number of days.
  • -ctime days: Finds files created in the last days number of days.
  • -atime days: Finds files accessed in the last days number of days.
  • -size size: Filters results by file size.
  • -regex pattern: Performs a regular expression match on file names.
  • -or expression1 expression2…: Combines multiple search expressions with an OR operator.
  • -and expression1 expression2…: Combines multiple search expressions with an AND operator.
  • -exclude exclude_expression: Excludes files matching the specified expression.
  • -onlyfiles: Restricts the search to files only.
  • -depth level: Specifies the depth to traverse directories (default: 1).
  • -multiprocess: Enables multi-process search for improved performance.
  • -local: Limits the search to the local volume only.
  • -onlyin directory: Specifies a specific directory to search within.

Examples

Search for all PNG image files:

mdfind kind:png

Find files containing the keyword “example” in their contents:

mdfind -onlyin /Users/my_user -c "kMDItemTextContent contains[cd] example"

Locate files modified within the past week:

mdfind -mtime 7

Search for files with a specific file size (e.g., 100MB):

mdfind -size 100mb

Combine multiple search expressions:

mdfind -or \(kind:file -size 500mb\) \(kind:directory -mtime 15\)

Common Issues

No results returned:

  • Ensure Spotlight indexing is enabled for the search scope.
  • Verify that the search expression is correct.
  • Try using a broader search term or removing unnecessary filters.

Slow search results:

  • Disable Spotlight indexing temporarily or restart it to resolve any performance issues.
  • Limit the search scope to a smaller directory or volume.
  • Disable the -multiprocess option if it slows down the search process.

Integration

Chain with other commands:

find . -type f -cmin -10 | mdfind -0

Create a custom Spotlight metadata key:

mdutil -i on -s "com.example.customKey" -t string /Users/my_user
mdfind -onlyin /Users/my_user -c "com.example.customKey contains[cd] value"
  • find: A versatile file system search utility with more advanced search options.
  • locate: An indexing-based file search tool for finding files based on their database.
  • xargs: A command-line utility used to execute a specified command multiple times, passing it arguments generated by another command.