# mdfind — Spotlight Search from the Command Line

> Practical guide to mdfind: macOS Spotlight search in the terminal — fast file and metadata queries over the Spotlight index, plus mdls and mdutil.

Source: https://www.jpkc.com/db/en/cheatsheets/macos/mdfind/

<!-- PROSE:intro -->
`mdfind` searches the Spotlight index straight from the command line – which makes it noticeably faster than `find`, because it queries a ready-made database instead of walking through directories. You can search not only by filename, but by content and metadata too: images above a certain resolution, files from a particular download, anything changed since yesterday. Using `kMDItem` attributes, you can build surprisingly precise queries. This guide walks you through the commands you reach for daily – rounded out with `mdls` for reading a file's metadata and `mdutil` for managing the index itself.
<!-- PROSE:intro:end -->

## mdfind — Basic Search

`mdfind '<query>'` — Search for files matching a query (like Spotlight).

```bash
mdfind 'invoice 2026'
```

`mdfind -name '<filename>'` — Search by filename only.

```bash
mdfind -name 'docker-compose.yml'
```

`mdfind -onlyin <dir> '<query>'` — Limit search to a specific directory.

```bash
mdfind -onlyin ~/Projects 'TODO'
```

`mdfind -count '<query>'` — Show only the count of matching files.

```bash
mdfind -count -name '*.pdf'
```

`mdfind -live '<query>'` — Continuously watch for new matches (live query).

```bash
mdfind -live 'screenshot'
```

## mdfind — Metadata Queries

`mdfind 'kMDItemContentType == "<type>"'` — Find files by content type (UTI).

```bash
mdfind 'kMDItemContentType == "public.png-image"'
```

`mdfind 'kMDItemKind == "<kind>"'` — Find files by kind.

```bash
mdfind 'kMDItemKind == "PDF Document"'
```

`mdfind 'kMDItemFSSize > <bytes>'` — Find files larger than a specific size.

```bash
mdfind 'kMDItemFSSize > 100000000'
```

`mdfind 'kMDItemContentModificationDate > $time.today(-7)'` — Find files modified in the last 7 days.

```bash
mdfind 'kMDItemContentModificationDate > $time.today(-7)'
```

`mdfind 'kMDItemWhereFroms == "*example.com*"'` — Find files downloaded from a specific domain.

```bash
mdfind 'kMDItemWhereFroms == "*github.com*"'
```

`mdfind 'kMDItemPixelWidth > 3000 && kMDItemContentType == "public.jpeg"'` — Find high-resolution JPEG images.

```bash
mdfind 'kMDItemPixelWidth > 3000 && kMDItemContentType == "public.jpeg"'
```

## mdls — File Metadata

`mdls <file>` — Show all Spotlight metadata attributes of a file.

```bash
mdls photo.jpg
```

`mdls -name <attribute> <file>` — Show a specific metadata attribute.

```bash
mdls -name kMDItemContentType document.pdf
```

`mdls -name kMDItemPixelWidth -name kMDItemPixelHeight <file>` — Show multiple specific attributes.

```bash
mdls -name kMDItemPixelWidth -name kMDItemPixelHeight photo.png
```

`mdls -name kMDItemWhereFroms <file>` — Show where a file was downloaded from.

```bash
mdls -name kMDItemWhereFroms ~/Downloads/installer.pkg
```

`mdls -name kMDItemDurationSeconds <file>` — Show duration of an audio/video file.

```bash
mdls -name kMDItemDurationSeconds song.mp3
```

## Spotlight Index Management

`mdutil -s /` — Show Spotlight indexing status for a volume.

```bash
mdutil -s /
```

`mdutil -i on /` — Enable Spotlight indexing on a volume.

```bash
sudo mdutil -i on /
```

`mdutil -i off <volume>` — Disable Spotlight indexing on a volume.

```bash
sudo mdutil -i off /Volumes/External
```

`mdutil -E /` — Erase and rebuild the Spotlight index.

```bash
sudo mdutil -E /
```

## Common Patterns

`mdfind -name '.env' -onlyin ~/Projects` — Find all .env files in your projects.

```bash
mdfind -name '.env' -onlyin ~/Projects
```

`mdfind 'kMDItemContentType == "com.apple.application-bundle"' -onlyin /Applications` — List all applications.

```bash
mdfind 'kMDItemContentType == "com.apple.application-bundle"' -onlyin /Applications
```

`mdfind -name '<filename>' | head -1 | xargs open` — Find a file and open it immediately.

```bash
mdfind -name 'readme.md' | head -1 | xargs open
```

`mdfind 'kMDItemFSCreationDate > $time.today(-1)' -onlyin ~/Downloads` — Find files downloaded today.

```bash
mdfind 'kMDItemFSCreationDate > $time.today(-1)' -onlyin ~/Downloads
```

<!-- PROSE:outro -->
## Conclusion

On indexed volumes, `mdfind` is almost always the faster choice over `find`: it queries the prebuilt Spotlight index instead of traversing the file system. The key caveat: it only finds what is actually indexed – system paths, excluded folders, or volumes with indexing turned off simply won't show up. When in doubt, check the status with `mdutil -s`, and use `mdls` to inspect a file's `kMDItem` attributes so you can refine your queries. Once you grasp how Spotlight collects metadata, a single precise query can replace many awkward `find` constructions.

## Further Reading

- [mdfind – man page (Apple Developer)](https://developer.apple.com/library/archive/documentation/Darwin/Reference/ManPages/man1/mdfind.1.html) – official reference for options and query syntax
- [File Metadata Query Expression Syntax](https://developer.apple.com/documentation/coreservices/file_metadata/mditem/common_metadata_attribute_keys) – overview of the `kMDItem` attributes
<!-- PROSE:outro:end -->

## Related Commands

- [caffeinate](https://www.jpkc.com/db/en/cheatsheets/macos/caffeinate/) – prevents the Mac from going to sleep
- [defaults](https://www.jpkc.com/db/en/cheatsheets/macos/defaults/) – reads and writes macOS preferences
- [diskutil](https://www.jpkc.com/db/en/cheatsheets/macos/diskutil/) – manages disks, partitions and volumes