MDUtil

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

Commands at a glance

  • Show whether the startup disk is indexedmdutil -s /
  • Show the status of every volumemdutil -sa
  • Erase and rebuild the startup disk's indexsudo mdutil -E /
  • Turn indexing off for a drivesudo mdutil -i off "/Volumes/My Drive"
  • Turn indexing back onsudo 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

OptionWhat it does
-sPrints the indexing status of the volumes given.
-aApplies the command to every volume, as in mdutil -sa.
-i on, -i offTurns indexing on or off. Indexing may wait while the disk is nearly full.
-EErases the index so that Spotlight builds a new one.
-dTurns off indexing and searching on the volume.
-vPrints more detail where there is some, as in mdutil -sv /.
-V volumeApplies the command to every index on that volume.
-tFinds a file from its file ID, given a volume path or device ID.
-r pluginsAsks Spotlight to import again the files handled by the importer plugins listed.
-L volumeLists the files in the volume's index folder. Needs sudo.
-P volumePrints the volume's Spotlight settings file, VolumeConfiguration.plist. Needs sudo.
-X volumeDeletes 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.
-pMeant 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 with sudo mdutil -i on and the volume's path.
  • Indexing and searching disabled.
    Indexing and searching are both off, as after -d. -i on turns both back on.
  • Indexing and searching disabled because of ".metadata_never_index" file at root of volume.
    An empty file named .metadata_never_index at 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. Put sudo in front of the command.
  • Must be root to run this command
    -L, -P and -X need sudo.
  • 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:

  1. Choose Apple menu > System Settings, then click Spotlight (or Siri & Spotlight) in the sidebar.
  2. Scroll down and click Search Privacy (or Spotlight Privacy) at the bottom.
  3. Drag the disk or folder into the list, or click the add button (+) and choose it.
  4. Wait a few seconds, select it in the list and click the remove button (–).
  5. 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:

  • mdfind searches the index from Terminal the way Spotlight does, as in mdfind "quarterly report", while mdfind -name invoice matches file names only. Add -onlyin and a folder to search just that folder.
  • mdls lists the metadata Spotlight holds for a file, as in mdls ~/Desktop/report.pdf.
  • mdimport -L lists the importer plugins Spotlight uses to read each kind of file.

Questions and answers

Does mdutil need sudo?

Checking the status doesn't. Changing the startup disk does, and so do -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?

It depends on how much is on the disk: Apple says indexing can take hours or even days. It finishes sooner while the Mac is idle and plugged in.

How do I know Spotlight is indexing?

In Activity Monitor, 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?

No. -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?

No. MDUtil (mdutil.com) is a set of free Markdown tools that run in your browser and convert Markdown to Word, PDF and HTML and back. Apple's mdutil is a command that comes with macOS, and the two only share a name.