Exclude a folder from Spotlight: keeping work out of the results

There are three separate reasons to exclude a folder from Spotlight, and they need different answers. One is privacy: a folder of client material or personal records that should not surface when someone types three letters with the screen shared. One is noise: a build directory or a dependency tree that fills every search with files nobody wants to open. One is work: an indexer grinding through a few hundred thousand generated files, which is felt as fans rather than as search results.

Most guides cover only the first reason, because the settings list is the obvious route. The settings list is the wrong tool for the second and third, and the reason is worth understanding before adding anything to it.

Which problem you are solving

Reason to exclude	The route that fits	What it costs
Privacy: keep a folder out of results	The privacy list in Spotlight settings	Search stops working inside apps that look in that folder
Noise: one file type is cluttering results	The hidden file types list in Spotlight settings	Nothing, but it applies everywhere rather than to one folder
Noise: build output or dependencies	A marker file inside the folder	Only works where you can drop a file
Work: stop indexing an entire disk	mdutil on that volume	No search at all on that volume

The privacy list is a short list of specific places, maintained by hand. It has no pattern matching, so a project layout that produces the same folder name in fifty repositories cannot be described in it. That single limitation explains most of the frustration people have with it.

The privacy list, and what it actually does

The list lives in the Apple menu, then System Settings, then Spotlight in the sidebar, behind the Search Privacy button. The pane states its purpose in one line: prevent Spotlight from searching these locations. Folders and disks are added by dragging them onto the list or with the add button, described in the interface as adding a folder or disk to exclude.

Two messages in that pane deserve more attention than they usually get.

The first is a warning about apps. Before the exclusion is applied, the pane asks whether you are sure, and explains the consequence: if you exclude this location from Spotlight searches, the search feature will not work in some applications. This is not a vague caution. Many apps use the same index to search their own library, so excluding a folder that an app stores its documents in breaks search inside that app while leaving the app otherwise normal. If the folder is a notes library, a photo library or a mail store, expect exactly that.

The second concerns Time Machine. Adding a Time Machine backup disk to the list produces a message rather than a plain exclusion: Spotlight will continue to search Time Machine backups but will not search other items on the disk. A backup folder cannot be added at all. If the goal is to keep something out of backups, that is a different system with its own list, reachable from the command line through tmutil addexclusion and checkable with tmutil isexcluded.

A third message is worth recognising when it appears: the item could not be added or removed because the location is not indexed. That means the exclusion is unnecessary, not that it failed.

The marker file, and why tools place it themselves

A folder can also tell the indexer to skip it. Placing an empty file named .metadata_never_index at the top of a directory takes that directory and everything beneath it out of the index:

touch ~/Projects/site/node_modules/.metadata_never_index

This is how developer tools handle the problem on their own. A machine with any real number of installed projects will already have several of these files, dropped by package managers and build tools into dependency directories, without anyone choosing to put them there. A related name, .metadata_never_index_unless_rootfs, does the same thing except on the startup volume.

Xcode takes a different route with the same intent: inside its derived data directory, the cache folders are named with a .noindex suffix, such as ModuleCache.noindex and SymbolCache.noindex, and the indexer skips folders named that way. Either convention works, and the suffix has the advantage of being visible in a folder listing rather than hidden as a dotfile.

The marker file is better than the privacy list for build output for three reasons. It travels with the folder, so it survives being moved. It can be created by a script, so a hundred folders is the same effort as one. And it lives with the project rather than in a system list nobody remembers checking.

It has one drawback worth stating. Because it is a hidden file inside the folder, there is nothing in System Settings that tells you it exists. Six months later, when search mysteriously ignores one directory, the settings list will look empty and the cause will be a dotfile. The habit that saves the time is checking for the marker as the second step whenever a folder is unexpectedly invisible, right after checking the settings list. A single ls -a at the top of the folder answers it.

Excluding a file type instead of a folder

Recent versions of macOS added a second list in the same Spotlight settings pane: hidden file types. Its instruction is explicit, telling you to click the add button or drag and drop the file type with the extension, and offering .png as the example.

This is the answer to a question people usually ask the wrong way. Stopping screenshots from filling the results is not a folder problem, because screenshots end up on the desktop, in downloads, in project folders and in message attachments. Hiding the extension handles all of those at once.

The trade is that it is global. An extension hidden here is hidden everywhere, so it is right for formats you never search for by content and wrong for anything you occasionally need. It is also worth writing down somewhere, because a search that fails for exactly one file type, a year later, is one of the harder things to diagnose from the symptom.

The same pane holds two related controls that are easy to confuse with exclusion. One is the list of result categories, with the rule stated next to it: only selected categories will appear in Spotlight search results. Switching off Documents there removes every document from every folder, which is a far blunter instrument than excluding one place. The other governs clipboard history, described as allowing Spotlight to search and display items you have copied, with the warning that personal and sensitive information may appear in search results. Anyone tightening up what Spotlight shows on a shared screen should look at that switch before hunting for folders to exclude, because copied passwords and tokens are a likelier exposure than any file.

The case the settings list cannot handle

The real problem, for anyone working with code, is that the folders to exclude are numerous, identically named, scattered, and constantly recreated. Dozens of node_modules directories, a vendor here, a target there, .venv in half the Python projects. The privacy list takes one path at a time and has no patterns, and re-adding paths every time a project is cloned is not a system.

Marker files solve it, because they can be placed in bulk:

find ~/Projects -type d -name node_modules -maxdepth 4 -exec touch {}/.metadata_never_index \;

Run something like that once and the folders are out of the index, including after a reinstall of the dependencies, because the marker sits at the top of the directory rather than inside the files that get replaced. Repeat it after cloning a batch of repositories, or make it part of whatever setup script a new project already runs.

Two cautions. Check what the pattern matches before adding -exec, by running the find on its own first. And keep -maxdepth on, because nested dependency trees can be surprisingly deep and there is no point marking a folder whose parent is already marked.

It is also worth being deliberate about which directories go on that list. Dependency trees and build output are safe, because nobody searches them by name and nothing useful is lost. Source directories are not, even when they are large, because searching inside code is exactly the case where an index earns its keep. The distinction to apply is whether the folder contains anything a person wrote. Generated output can always be regenerated and never needs finding; written material is the whole reason search exists.

What excluding a folder does not do

This is where expectations most often miss.

Route to the files	Affected by a Spotlight exclusion
Spotlight window and Finder search	Yes, the files stop appearing
mdfind	Yes, it reads the same index
Search inside apps that use the index	Yes, which is what the warning is about
find, grep, ls in a terminal	No, these walk the file system directly
Time Machine and other backups	No, that is a separate exclusion list
File permissions and who can open the folder	No, nothing about access changes

The last two rows matter most. An excluded folder is still backed up, still readable by anything running as your user, and still visible to anyone who opens it. Exclusion hides a folder from a search feature. It is tidying, and for noise and indexer work it is exactly the right tool. It is not a security measure, and treating it as one is the mistake worth avoiding. If the contents genuinely need protecting, that is an encrypted disk image or an encrypted volume, and the exclusion is at most a convenience on top.

Confirm it took effect

Do not take the setting on trust. Ask the index directly:

mdfind -count -onlyin ~/Projects/site/node_modules "kMDItemFSName == '*'c"
mdfind -count -onlyin ~/Projects/site "kMDItemFSName == '*.js'c"

The first should fall to zero. The second, on a sibling path that is still indexed, should not, which is what proves the exclusion is scoped rather than something broader having gone wrong. Excluding a folder does not remove existing records instantly in every case, so if the first count is still high, give it a few minutes and check again before changing anything else.

Working this way, checking a count before and after a change, is also the habit that makes the whole subject manageable. The friction is that it means having a shell next to the folder in question rather than in a separate window with the path typed twice. A file manager with a built-in terminal removes that step, since the folder in view and the shell prompt are the same place. The features page covers how that works, and the FAQ answers what it does and does not index on its own.

What to change first

Decide which of the three problems is yours. For privacy, use the Search Privacy list and read the warning about apps before confirming. For build output and dependencies, skip the settings entirely and place .metadata_never_index markers with a single find command, which handles every project at once and survives reinstalls. Then verify with mdfind -count on the folder and on a sibling, from a shell that is already sitting where the folders are, which is what Atriens is built around.