The mdutil command on Mac
mdutil is the Terminal command that comes with macOS for managing Spotlight's search indexes. It shows whether a disk is indexed, turns indexing off or on, and erases an index so that Spotlight builds a new one.
Tried on macOS Sequoia 15.7
MDUtil, the site this page is on, is a set of free Markdown tools and has no connection with Apple. The mdutil command comes with every Mac.
Commands at a glance
- Show whether the startup disk is indexed
mdutil -s / - Show the status of every volume
mdutil -sa - Erase and rebuild the startup disk's index
sudo mdutil -E / - Turn indexing off for a drive
sudo mdutil -i off "/Volumes/My Drive" - Turn indexing back on
sudo mdutil -i on "/Volumes/My Drive"
Check whether Spotlight indexes a disk
-s prints the indexing status of the volume you name. / is the startup disk, and other drives are mounted under /Volumes. Checking the status doesn't need sudo.
mdutil -s /
/:
Indexing enabled.
Add -a to list every volume Spotlight knows about. Since macOS Catalina the list also shows /System/Volumes/Data, the volume that holds your files, and /System/Volumes/Preboot.
mdutil -sa
The path has to be where a volume is mounted. An ordinary folder, such as your home folder, gives Error: unknown indexing state.
Rebuild the Spotlight index
When Spotlight or a Finder search misses files that are on the disk, or keeps showing files you deleted long ago, the index may be damaged. -E erases a volume's index, and Spotlight starts building a new one straight away:
sudo mdutil -E /
sudo asks for your Mac login password, and nothing shows while you type it. For an external drive, give its path under /Volumes, in quotes if the name has spaces:
sudo mdutil -E "/Volumes/My Drive"
There's no need to turn indexing off first. Apple notes that indexing can take hours or even days, depending on how much is on the disk, and finishes sooner while the Mac is idle and plugged in. In the meantime Activity Monitor shows mds, mds_stores and mdworker using the CPU.
Rebuild only when the index is really wrong. Spotlight also indexes for a while after a macOS update or when many files change, and erasing the index then makes it start again from nothing.
Turn indexing off or on
-i off stops Spotlight from indexing a volume, which suits a drive that only holds backups or temporary files. Searches then can't look inside its files.
sudo mdutil -i off "/Volumes/My Drive"
-i on turns indexing back on, and Spotlight brings the volume's index up to date:
sudo mdutil -i on "/Volumes/My Drive"
-d also turns off searching on the volume, and the status then reads Indexing and searching disabled. -i on undoes that too.
Turning indexing off for the startup disk is rarely a good idea, because Spotlight uses that index to find apps, documents, email and settings. To keep a few folders out of search results, add them to the privacy list in Spotlight settings instead.
Every option
| Option | What it does |
|---|---|
-s | Prints the indexing status of the volumes given. |
-a | Applies the command to every volume, as in mdutil -sa. |
-i on, -i off | Turns indexing on or off. Indexing may wait while the disk is nearly full. |
-E | Erases the index so that Spotlight builds a new one. |
-d | Turns off indexing and searching on the volume. |
-v | Prints more detail where there is some, as in mdutil -sv /. |
-V volume | Applies the command to every index on that volume. |
-t | Finds a file from its file ID, given a volume path or device ID. |
-r plugins | Asks Spotlight to import again the files handled by the importer plugins listed. |
-L volume | Lists the files in the volume's index folder. Needs sudo. |
-P volume | Prints the volume's Spotlight settings file, VolumeConfiguration.plist. Needs sudo. |
-X volume | Deletes the volume's index folder without turning indexing off. Spotlight builds it again after a restart, when the volume is mounted again, or after -i or -E. Needs sudo. |
-p | Meant to copy locally cached indexes back to network drives. On macOS Sequoia it answers Error: datastore publishing not implemented. |
What mdutil's messages mean
Indexing enabled.
Spotlight indexes the volume as usual.Indexing disabled.
Indexing is off. Turn it on withsudo mdutil -i onand the volume's path.Indexing and searching disabled.
Indexing and searching are both off, as after-d.-i onturns both back on.Indexing and searching disabled because of ".metadata_never_index" file at root of volume.
An empty file named.metadata_never_indexat the top of the volume keeps Spotlight out. Delete the file, then turn indexing on.Error: unknown indexing state.
The path isn't where a volume is mounted. Use/or a drive under/Volumes.Error: unexpected indexing state. kMDConfigSearchLevelTransitioning
The volume is still changing state after an earlier command. Wait a few seconds and run it again.Error: Index is already changing state. Please try again in a moment.
The same: wait a moment and try again.Error: unable to perform operation. Try as root. (-1)
The change needs administrator rights. Putsudoin front of the command.Must be root to run this command
-L,-Pand-Xneedsudo.Error: invalid path
Nothing exists at that path. Check the spelling, and put names with spaces in quotes.Spotlight server is disabled.
mdutil couldn't reach Spotlight's background service. Restart the Mac and check again.No index.
The volume has no Spotlight index yet.Index is read-only.
Spotlight can search the existing index but doesn't update it.Server search enabled.
A network volume is searched with the server's own index.
Rebuild the index without Terminal
Apple's own way to rebuild the index of a disk or folder goes through Spotlight settings:
- Choose Apple menu > System Settings, then click Spotlight (or Siri & Spotlight) in the sidebar.
- Scroll down and click Search Privacy (or Spotlight Privacy) at the bottom.
- Drag the disk or folder into the list, or click the add button (+) and choose it.
- Wait a few seconds, select it in the list and click the remove button (–).
- Click Done. Spotlight indexes that disk or folder again.
Apple describes these steps in About Spotlight indexing and search results.
Related commands
mdutil looks after the index. These commands, which also come with macOS, use it:
mdfindsearches the index from Terminal the way Spotlight does, as inmdfind "quarterly report", whilemdfind -name invoicematches file names only. Add-onlyinand a folder to search just that folder.mdlslists the metadata Spotlight holds for a file, as inmdls ~/Desktop/report.pdf.mdimport -Llists the importer plugins Spotlight uses to read each kind of file.
Questions and answers
Does mdutil need sudo?
-L, -P and -X on any volume. Without it mdutil answers Try as root or Must be root to run this command.How long does rebuilding the Spotlight index take?
How do I know Spotlight is indexing?
mds, mds_stores and mdworker use the CPU while Spotlight indexes. The Spotlight window also shows a progress bar at the top while search isn't ready, though indexing can go on after the bar is gone.Does erasing the index delete my files?
-E removes only Spotlight's index, which macOS builds again from your files. Search results are incomplete until the new index is ready.Is MDUtil the same as Apple's mdutil?
mdutil is a command that comes with macOS, and the two only share a name.