Spotlight is the name of app for local (desktop) search for macOS.

Contents

1 Introduction for Beginners
2 Medium- and Advanced- level users
3 Advanced – Backend, Frontend
4 Alternatives to Spotlight
5 Command Line, man pages, …
6 Problems Research
- - 6.0.1 The Problems: Spotlight won’t work
  - 6.0.2 The Solutions: Troubleshooting Spotlight
- 6.1 2026-08-22 Not Finding Items

Introduction for Beginners

(Mac User Guide) Search for anything with Spotlight on Mac – support.apple.com/guide/mac-help/search-with-spotlight-mchlp1008/mac
(Tips for use in /is/search/spotlight/tips)
en.wikipedia.org/wiki/Spotlight_(Apple)
google.com/search?q=apple+spotlight

Medium- and Advanced- level users

J&P-LOCAL R&D: shortcuts://run-shortcut?name=Spotlight%20Search&input=project%20report

Advanced – Backend, Frontend

Components	Spotlight, by Apple	Other
Backend (database, tools)	Database with indexed contents Tools for creating / maintaining index db, et c	(See Search! macOS-Focus – /is/apps/macos/search/)
Frontend (search, present)	Spotlight application (command+Space) msl	(See Search! macOS-Focus – /is/apps/macos/search/)

Components

Spotlight, by Apple

Other

Backend (database, tools)

Database with indexed contents
Tools for creating / maintaining index db, et c

(See Search! macOS-Focus – /is/apps/macos/search/)

Frontend (search, present)

Spotlight application (command+Space)
msl

(See Search! macOS-Focus – /is/apps/macos/search/)

A quite great depiction of functionality and tools:

From eclecticlight.co/2023/07/19/searching-icloud-drive-with-spotlight/

Alternatives to Spotlight

See Search! macOS-Focus – /is/apps/macos/search/

Command Line, man pages, …

`mds` Command

MDS(8)                      System Manager's Manual                     MDS(8)

NAME
     mds – metadata server

SYNOPSIS
     mds

DESCRIPTION
     mds is the metadata server.  It serves all clients of the metadata APIs,
     including Spotlight.

     There are no configurations to mds, and users should not run mds
     manually.

SEE ALSO
     mdfind(1), mdls(1), mdutil(1)

Mac OS X                       January 19, 2006                       Mac OS

`mdfind` Command

Extract from man page:

mdfind(1)                   General Commands Manual                  mdfind(1)

NAME
     mdfind – finds files matching a given query

SYNOPSIS
     mdfind [-live] [-count] [-onlyin directory] [-name fileName] query

DESCRIPTION
     The mdfind command consults the central metadata store and returns a list
     of files that match the given metadata query. The query can be a string
     or a query expression.

     The following options are available:
...

google.com/search?q=using+mdfind

mdfind 'search!' Command

macos:~ joe mdfind kind:folder -name 'search!'
2023-05-16 18:06:12.227 mdfind[55946:6186246] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2023-05-16 18:06:12.227 mdfind[55946:6186246] [UserQueryParser] Loading keywords and predicates for locale "en"
/Users/joe/Library/CloudStorage/Dropbox/Research!/IT/Apps! Applications! macOS/Desktop search!
/Users/joe/Library/CloudStorage/Dropbox/Research!/IT/Search!! Finding stuff
/Users/joe/Library/CloudStorage/Dropbox/Research!/IT/Search!! Finding stuff/Search! different types of search implementations terms autocomplete contextual
macos:~ joe$

`mdls` Command

Extract from man page:

MDLS(1)                     General Commands Manual                    MDLS(1)

NAME
     mdls – lists the metadata attributes for the specified file

SYNOPSIS
     mdls [-name attributeName] [-raw [-nullMarker markerString]] file ...

DESCRIPTION
     The mdls command prints the values of all the metadata attributes
     associated with the files provided as an argument.

     The following options are available:
...

`mdutil` Command

Extract from man page:

mdutil(1)                   General Commands Manual                  mdutil(1)

NAME
     mdutil – manage the metadata stores used by Spotlight

SYNOPSIS
     mdutil [-pEsav] [-i on | off] mountPoint ...

DESCRIPTION
     The mdutil command is useful for managing the metadata stores for mounted
     volumes.

     The following options are available:
...

`mdimport` Command

Extract from man page:

mdimport(1)                 General Commands Manual                  mdimport(1)

NAME
     mdimport – import file hierarchies into the metadata datastore.

SYNOPSIS
     mdimport [-itpAXLr] [-d level] [-o -outputfile] [ file | directory ... ]

DESCRIPTION
     mdimport is used to test Spotlight plug-ins, list the installed plug-ins and
     schema, and re-index files handled by a plug-in when a new plug-in is installed.

     The following options are available:
...

Problems Research

Restart Spotlight-Related Services
1. SystemUIServer
2. Spotlight
3. mds
Restart Your Mac
Check Your Keyboard Shortcuts
Check Your Spotlight Settings
Update Your Mac
Check for Disk Errors
Reindex Spotlight Search
Disable and Reactivate Spotlight Index
Clear the Mac’s Cache

SystemUIServer
- google.com/search?q=systemuiserver
Spotlight
- /System/Library/CoreServices/Spotlight.app
- google.com/search?q=%2FSystem%2FLibrary%2FCoreServices%2FSpotlight.app
mds
- google.com/search?q=macos+mds
- osxdaily.com/2010/08/05/mds-mac/

osxdaily.com/2007/02/15/spotlight-wont-work-fix-a-broken-spotlight-menu-with-these-troubleshooting-tips/

The Problems: Spotlight won’t work

There are several incarnations of Spotlight problems that I have personally run into, they are:

Problem #1) Spotlight menu icon highlights, but no search form appears
Problem #2) Spotlight search form appears, but no results are shown
Problem #3) Spotlight search works, but results are poor and incomplete

While not entirely sure what causes any of these problems, try these troubleshooting methods that frequently work to repair Spotlight:

The Solutions: Troubleshooting Spotlight

Solution #1: Kill SystemUIServer

Launch ‘Activity Monitor’ (located in /Applications/Utilities/)
Locate the process ‘SystemUIServer’, highlight it, and click the red button “Quit Process”
Within a few seconds the menubar will rebuild itself and often Spotlight will magically work

Solution #2: Rebuild the Spotlight Index manually

Launch ‘Terminal’ (located in /Applications/Utilities/)
At the command prompt, type this exactly:sudo mdutil -E /
You will be asked for your password, provide it, as this command requires administrator privelages to run
You will receive a confirmation message saying that index will be rebuilt
Wait until index is finished rebuilding, this can take a while depending on the size of your hard drive, amount of files, etc.
Note: You can also rebuild the Spotlight index with MainMenu, mentioned in Solution #4

Solution #3: Change Desktop Resolution

This is a strange fix but it works everytime for me when my Spotlight menu icon highlights but the search form doesn’t appear
Open “System Preferences” via the Apple Menu
Click ‘Displays’ and select a resolution smaller than what you are currently using, 640×480 seems to always work
Select your native resolution again, changing your screen resolution back to normal
The Spotlight search tray will magically become available again

Solution #4: Clear caches and preferences

Clear caches and preferences relating to Spotlight, this is best done through either the free tool OnyX, or the free tool MainMenu, we recommend MainMenu because it’s easier for novices
- Download MainMenu here
- Download OnyX here
Install MainMenu
- a little Hammer and Wrench icon will appear in your menubar
- navigate down to ‘Cleaning’ and clean out User Cache, System Cache, and Font Caches
Note: Some users discover that just cleaning the Font caches is adequate to repair a screwy Spotlight, but it won’t hurt to clear them all

Solution #5: Reboot your Mac

This should almost be listed as #1 just because sometimes a simple reboot will fix Spotlight, but if I can avoid a reboot I will, and often, a reboot isn’t good enough

What do MDS and MDWorker have to do with Spotlight?
The MDS process and mdworker processes usually run concurrently on your Mac when Spotlight is indexing your Mac. Let the processes finish running to complete a relevant search index of your Mac filesystem.

Hopefully that covers it, and Spotlight should be working good as new again. If we missed something, feel free to contribute in the comments below.

Happy Spotlighting!

2026-08-22 Not Finding Items

(After a quite major operations involving creating a brand-new user and copying lots of materials from an older user, realize having problems finding essentially ANYTHING using Spotlight. Apps and other misc – YES; (own) files and folders – NO.

Q: mdls shows some result but mdfind does not, what’s wrong and how to fix?

The discrepancy occurs because mdfind relies on the Spotlight database, which may be incomplete, corrupted, or excluding specific files/folders, while mdls queries the file directly using the Spotlight API without relying on the global search index.

To resolve this, you can:

Rebuild the Spotlight Index: Use sudo mdutil -E / to erase and rebuild the index for the main volume, which often resolves missing results.
Check Indexing Exclusions: Ensure the file or folder is not in the Privacy list in System Settings > Siri & Spotlight > Spotlight Privacy, which prevents Spotlight from indexing it.
Use mdls for Direct Inspection: If mdfind fails, use mdls <filename> to verify that the metadata attributes (like kMDItemContentType or kMDItemFSName) are present and correctly populated.
Verify File Type Support: Some file types (like .wsdl) may lack a Spotlight importer, meaning they are not indexed for content search; check if the file type is supported by using mdls -name kMDItemContentType <file>.
Use mdfind -onlyin for Specific Directories: If global search is broken or slow, use mdfind -onlyin /path/to/dir "query" to force a local scan that may bypass index issues.
Check for Index Corruption: If rebuilding fails, ensure the disk is not read-only and has sufficient space, as index corruption can stem from filesystem errors.

Try mdls

Checking ‘(like kMDItemContentType or kMDItemFSName) are present and correctly populated’ and it turns out the second actually has ‘(null’) – not good.

joe@MB2314 ~ % mdls ~/Documents/Researchƒ
_kMDItemDisplayNameWithExtensions      = "Researchƒ"
kMDItemContentCreationDate             = 2026-08-21 12:38:08 +0000
kMDItemContentCreationDate_Ranking     = 2026-08-21 00:00:00 +0000
kMDItemContentModificationDate         = 2026-08-23 11:49:09 +0000
kMDItemContentModificationDate_Ranking = 2026-08-23 00:00:00 +0000
kMDItemContentType                     = "public.folder"
kMDItemContentTypeTree                 = (
"public.folder",
"public.directory",
"public.item"
)
kMDItemDateAdded                       = 2026-08-22 12:18:08 +0000
kMDItemDateAdded_Ranking               = 2026-08-22 00:00:00 +0000
kMDItemDisplayName                     = "Researchƒ"
kMDItemDocumentIdentifier              = 0
kMDItemFSContentChangeDate             = 1970-01-01 00:00:00 +0000
kMDItemFSCreationDate                  = 1970-01-01 00:00:00 +0000
kMDItemFSCreatorCode                   = ""
kMDItemFSFinderFlags                   = 0
kMDItemFSHasCustomIcon                 = 0
kMDItemFSInvisible                     = 0
kMDItemFSIsExtensionHidden             = 0
kMDItemFSIsStationery                  = 0
kMDItemFSLabel                         = 0
kMDItemFSName                          = (null)
kMDItemFSNodeCount                     = 0
kMDItemFSOwnerGroupID                  = 0
kMDItemFSOwnerUserID                   = 0
kMDItemFSSize                          = 0
kMDItemFSTypeCode                      = ""
kMDItemInterestingDate_Ranking         = 2026-08-23 00:00:00 +0000
kMDItemKind                            = "Folder"

Which thus makes sense why mdfind fails finding:

joe@MB2314 ~ % mdfind kind:folder -name 'Researchƒ'
2026-08-23 06:50:13.240 mdfind[98687:4189825] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2026-08-23 06:50:13.240 mdfind[98687:4189825] [UserQueryParser] Loading keywords and predicates for locale "en"

joe@MB2314 ~ % mdfind  -name 'Researchƒ'
2026-08-23 06:51:29.717 mdfind[98739:4191192] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2026-08-23 06:51:29.717 mdfind[98739:4191192] [UserQueryParser] Loading keywords and predicates for locale "en"

Run mdutil to rebuild index

Ok, start rebuilding, will take time…

joe@MB2314 ~ % date; sudo mdutil -E /
Sun Aug 23 06:52:34 CDT 2026
/:
Indexing enabled.
joe@MB2314 ~ % mdfind  -name 'Researchƒ'
2026-08-23 06:53:40.400 mdfind[98830:4193693] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2026-08-23 06:53:40.401 mdfind[98830:4193693] [UserQueryParser] Loading keywords and predicates for locale "en"

joe@MB2314 ~ % mdls ~/Documents/Researchƒ
_kMDItemDisplayNameWithExtensions      = "Researchƒ"
kMDItemContentCreationDate             = 2026-08-21 12:38:08 +0000
kMDItemContentCreationDate_Ranking     = 2026-08-21 00:00:00 +0000
kMDItemContentModificationDate         = 2026-08-23 11:49:09 +0000
kMDItemContentModificationDate_Ranking = 2026-08-23 00:00:00 +0000
kMDItemContentType                     = "public.folder"
kMDItemContentTypeTree                 = (
"public.folder",
"public.directory",
"public.item"
)
kMDItemDateAdded                       = 2026-08-22 12:18:08 +0000
kMDItemDateAdded_Ranking               = 2026-08-22 00:00:00 +0000
kMDItemDisplayName                     = "Researchƒ"
kMDItemDocumentIdentifier              = 0
kMDItemFSContentChangeDate             = 1970-01-01 00:00:00 +0000
kMDItemFSCreationDate                  = 1970-01-01 00:00:00 +0000
kMDItemFSCreatorCode                   = ""
kMDItemFSFinderFlags                   = 0
kMDItemFSHasCustomIcon                 = 0
kMDItemFSInvisible                     = 0
kMDItemFSIsExtensionHidden             = 0
kMDItemFSIsStationery                  = 0
kMDItemFSLabel                         = 0
kMDItemFSName                          = (null)
kMDItemFSNodeCount                     = 0
kMDItemFSOwnerGroupID                  = 0
kMDItemFSOwnerUserID                   = 0
kMDItemFSSize                          = 0
kMDItemFSTypeCode                      = ""
kMDItemInterestingDate_Ranking         = 2026-08-23 00:00:00 +0000
kMDItemKind                            = "Folder"

joe@MB2314 ~ %

RESTARTED Whole Computer – FIXED IT

And THAT seems to have helped alright! Now kMDItemFSName is properly populated.

[Restored Aug 23, 2026 at 07:01:34]
Last login: Sun Aug 23 07:01:34 on ttys010
You have mail.
joe@MB2314 ~ %  mdls ~/Documents/Researchƒ
_kMDItemDisplayNameWithExtensions      = "Researchƒ"
kMDItemContentCreationDate             = 2026-08-21 12:38:08 +0000
kMDItemContentCreationDate_Ranking     = 2026-08-21 00:00:00 +0000
kMDItemContentModificationDate         = 2026-08-23 11:49:09 +0000
kMDItemContentModificationDate_Ranking = 2026-08-23 00:00:00 +0000
kMDItemContentType                     = "public.folder"
kMDItemContentTypeTree                 = (
"public.folder",
"public.directory",
"public.item"
)
kMDItemDateAdded                       = 2026-08-22 12:18:08 +0000
kMDItemDateAdded_Ranking               = 2026-08-22 00:00:00 +0000
kMDItemDisplayName                     = "Researchƒ"
kMDItemDocumentIdentifier              = 0
kMDItemFSContentChangeDate             = 2026-08-23 11:49:09 +0000
kMDItemFSCreationDate                  = 2026-08-21 12:38:08 +0000
kMDItemFSCreatorCode                   = ""
kMDItemFSFinderFlags                   = 1024
kMDItemFSHasCustomIcon                 = (null)
kMDItemFSInvisible                     = 0
kMDItemFSIsExtensionHidden             = 0
kMDItemFSIsStationery                  = (null)
kMDItemFSLabel                         = 0
kMDItemFSName                          = "Researchƒ"
kMDItemFSNodeCount                     = 40
kMDItemFSOwnerGroupID                  = 20
kMDItemFSOwnerUserID                   = 507
kMDItemFSSize                          = (null)
kMDItemFSTypeCode                      = ""
kMDItemInterestingDate_Ranking         = 2026-08-23 00:00:00 +0000
kMDItemKind                            = "Folder"
joe@MB2314 ~ %

joe@MB2314 ~ % mdfind -name 'Researchƒ' 
2026-08-23 10:51:30.018 mdfind[14387:331897] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2026-08-23 10:51:30.018 mdfind[14387:331897] [UserQueryParser] Loading keywords and predicates for locale "en"
/Users/joe/Documents/Researchƒ
/Users/joe/Documents/Researchƒ/IT! RD/Apps! Applications! macOS/Dropbox!/Problems,Troubles,Troubleshooting/ \
  2024 and earlier/2018/2018-05-04.. May-Jun-Jul, major resyncs, from ƒ to # to !/ \
  2018-05-12 07.54.10 Changed Researchƒ to Research! (!!! major change, inclde affecting Shared to CV).png
/Users/joe/Documents/Researchƒ/IT! RD/Apps! Applications! macOS/Dropbox!/Problems,Troubles,Troubleshooting/ \
  2024 and earlier/2018/2018-05-04.. May-Jun-Jul, major resyncs, from ƒ to # to !/ \
  2018-05-15 17.27.30 Finder- Researchƒ.png
...

Note: mdfind Syntax: kind:folder seems to have to be AFTER (e.g.) -name

Maybe this version of macOS (Tahoe, 26.6.2)…

joe@MB2314 ~ % mdfind kind:folder -name 'Researchƒ'
2026-08-23 10:51:48.367 mdfind[14405:332285] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2026-08-23 10:51:48.367 mdfind[14405:332285] [UserQueryParser] Loading keywords and predicates for locale "en"
joe@MB2314 ~ %

No find.

joe@MB2314 ~ % mdfind -name "Researchƒ" kind:folder
2026-08-23 10:56:19.689 mdfind[14681:337965] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2026-08-23 10:56:19.690 mdfind[14681:337965] [UserQueryParser] Loading keywords and predicates for locale "en"
/Users/joe/Documents/Researchƒ

(Did find.)

joe@MB2314 ~ % mdfind kind:folder -name 'Researchƒ'
2026-08-23 10:56:29.323 mdfind[14691:338097] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2026-08-23 10:56:29.324 mdfind[14691:338097] [UserQueryParser] Loading keywords and predicates for locale "en"

joe@MB2314 ~ % mdfind kind:folder -name "Researchƒ"
2026-08-23 10:56:35.215 mdfind[14696:338225] [UserQueryParser] Loading keywords and predicates for locale "en_US"
2026-08-23 10:56:35.216 mdfind[14696:338225] [UserQueryParser] Loading keywords and predicates for locale "en"

joe@MB2314 ~ %

eop

Introduction for Beginners

Medium- and Advanced- level users

Advanced – Backend, Frontend

Alternatives to Spotlight

Command Line, man pages, …

mds Command

mdfind Command

mdls Command

mdutil Command

mdimport Command

Problems Research

The Problems: Spotlight won’t work

The Solutions: Troubleshooting Spotlight

2026-08-22 Not Finding Items

Try mdls

Run mdutil to rebuild index

RESTARTED Whole Computer – FIXED IT

Note: mdfind Syntax: kind:folder seems to have to be AFTER (e.g.) -name

`mds` Command

`mdfind` Command

`mdls` Command

`mdutil` Command

`mdimport` Command