Finder tags: what it does and where it breaks down

Most people meet Finder tags twice. The first time is pleasant: a colour appears next to a filename, a coloured entry shows up in the sidebar, and files that live in five different folders line up in one list. The second time is not pleasant. A file that was tagged last month opens with no tag on it, or a tagged folder copied to a USB stick arrives on another Mac with nothing attached, or the sidebar entry returns eleven files when it used to return forty.

Both experiences come from the same fact, and nobody explains it at the moment the tag is created. A tag is not a property of the Finder. It is a small piece of data written onto the file itself, and everything that happens afterwards depends on whether the next program to touch that file knows the data is there. What follows is the mechanism, the exact places where it holds, and the exact places where it does not.

A tag is written onto the file, not stored in a list

When a tag is applied, macOS writes an extended attribute onto the file named com.apple.metadata:_kMDItemUserTags. Extended attributes are a feature of the file system rather than of any application. They ride alongside the file's contents, invisible in a normal directory listing, readable by anything that asks for them.

The attribute holds a small binary property list containing an array of strings. Each string is the tag's name, followed by an index for the colour when a colour has been attached to it. That is the whole record. There is no central database that maps files to tags, and no per folder list that has to stay in step with the disk.

Two consequences follow immediately, and they explain most of the confusion around tags.

The first is that a tagged file stays tagged when it moves. Drag it to a different folder, rename it, put it inside three levels of nesting, and the attribute travels with it because it is part of the file. This is the behaviour people expect from tags and the reason the feature is worth using at all.

The second is that any operation which creates a new file rather than moving the existing one produces an untagged result. A copy made by the Finder preserves extended attributes. A copy made by a program that reads the bytes and writes them somewhere new does not, unless that program was written to carry attributes across. Saving a document under a new name in an editor produces a new file, which means a new file with no tags on it.

To see what is actually attached to a given file, mdls -name kMDItemUserTags somefile.pdf prints the tag names in readable form, and xattr -l somefile.pdf lists every extended attribute the file carries. Both are useful when a tag has apparently disappeared, because they separate "the tag is gone" from "the tag is there and something else is wrong".

Seven colours in the sidebar, any number of names

The colour side of tags is capped and the naming side is not, which surprises people who assume the seven colours are the whole feature.

macOS ships seven colours: red, orange, yellow, green, blue, purple and grey. That set is fixed. A tag may carry one of them or none at all, and the colour is what produces the dot next to the filename and the tinted entry in the sidebar.

Tag names have no such limit. Any string can become a tag, any number of tags can exist on the system, and a single file can carry as many tags as needed. A quarterly invoice can be client-a, invoice and 2026 at once, with only one of the three carrying a colour.

The seven slots that do matter are in Finder Settings, under the Tags section. The list there controls which tags appear in the sidebar, and the Favourite Tags area at the bottom holds the tags that show up in the right click menu and in the tag row of the share sheet. Those favourites are the ones that get applied in practice, because they are the ones reachable without typing. Everything else requires the Get Info panel or the tag field, which takes long enough that it stops happening after the first week.

This is the first design decision worth making deliberately: which small set of tags earns a colour and a favourite slot, and which ones stay as plain names that are typed when needed.

Folders decide location, tags decide attributes

A file occupies exactly one folder. It can carry many tags. That asymmetry is the entire argument for using both.

Folder trees answer questions about where something belongs in a structure. Tags answer questions that cut across the structure: everything urgent, everything belonging to one client, everything that still needs review, regardless of which project directory it was filed under.

The practical form of that second question is the Smart Folder. File then New Smart Folder builds a saved query, and a query can combine a tag with a file type, a date range, or a folder scope. Saved searches live in ~/Library/Saved Searches as .savedSearch files, and adding one to the Finder sidebar turns a recurring question into a single click.

The failure mode here is predictable. Tags get used as a second folder tree, with names that duplicate the directory names they sit inside, and the result is twice the filing work for no additional answer. A tag earns its place when it describes something the folder path cannot: a state that changes over time, a person, an urgency, a stage in a process. When a tag and a folder always mean the same thing, the tag is redundant.

The index decides whether tags are findable

Tags are stored on files. Searching for them is done through Spotlight's index. Those are two separate systems, and when the second one is missing the first one still looks fine.

Clicking a tag in the sidebar runs a Spotlight query. If the volume holding the files is not indexed, the query returns nothing even though every file still carries its attribute. This is the ordinary situation on external drives with indexing turned off, on network volumes, and on any location added to the Spotlight Privacy list in System Settings.

mdutil -s /Volumes/Archive reports whether indexing is enabled for a given volume, and mdfind "kMDItemUserTags == 'invoice'" runs the same query the sidebar runs, from a shell, which makes it obvious whether the problem is the tag or the index. A query that returns results in one location and nothing in another is an indexing problem every time.

The rebuild path, when the index is genuinely damaged, is mdutil -E / to erase and rebuild it, which takes anywhere from minutes to hours depending on the size of the disk. During that period searches are incomplete, which is worth knowing before starting it in the middle of a working day.

Where tags survive a move and where they fall off

The honest answer is that survival depends on the destination and the tool, not on the tag. This table covers the routes that come up most often.

What happens to the file	State of the tag afterwards
Moved or copied inside the same Mac by the Finder	Kept
Copied to an APFS or HFS+ external drive	Kept
Copied to an exFAT or FAT drive	Stored in a hidden ._ sidecar file next to it
Copied to an SMB share	Depends on the server, often via a ._ sidecar
Compressed with the Finder's Compress command	Kept inside the archive
Unpacked with a third party archiver	Often discarded
Synced through iCloud Drive	Kept, and visible in the Files app
Uploaded to a web based storage service	Not carried, the service has its own labels
Attached to an email	Lost
Copied with cp without -p, or rsync without -X	Lost
Committed to a git repository	Not tracked

Two rows deserve more than a line. The ._ sidecar is the AppleDouble format, a companion file that holds the attributes a foreign file system cannot store. It works, as long as both files travel together. Moving the visible file on its own, or copying it through a tool that skips dotfiles, leaves the tag behind on the old volume.

The email row is the one that causes arguments. A tagged file sent to a colleague arrives with no tag, and no error appears anywhere, because tags were never part of what an attachment carries. Anything that needs to survive a handoff belongs in the filename or in the document, not in a tag.

The three places the system starts to strain

Vocabulary sprawl comes first. Tags are easy to create, including by accident, since typing a name that does not exist yet creates it. After a few months the tag list holds urgent, Urgent, urgent2 and asap, and no single one of them returns the right set. The Finder Settings tag list is where this gets cleaned up, and renaming a tag there updates every file that carries it, which is the one bulk operation the interface offers.

Applications that rewrite files come second. Many editors save by writing a temporary file and renaming it over the original, which is the safe way to avoid a half written document. The side effect is a new file, and the extended attributes of the old one do not always make the trip. Files that are edited constantly are therefore the worst candidates for tags, and files that are written once and referred to afterwards are the best.

Other people's machines come third. A tag name is a local string, and the colour attached to it comes from the local configuration. A file tagged red on one Mac and opened on another where red has never been defined shows a colour with no meaning attached. In shared folders this produces tag lists that slowly fill with names nobody recognises.

What changes when the terminal sits in the same window

Narrowing is where tags are strong. A saved search that returns the eighteen files matching a tag has done something no folder tree can do in one step. The work that follows is where the friction appears, because renaming those eighteen files, moving them somewhere else, or checking what is inside them is not what the Finder is fastest at.

The usual workaround is to run the same query again with mdfind and pipe the result into a command, which means building the narrowing twice in two different places. A file manager that keeps the folder view, a terminal and an assistant in one window removes that second step, since the set produced by the query is already the set the command acts on. The feature list describes what one window covers, and the comparison sets that against the dual pane and transfer oriented tools that solve a different part of the problem.

What to change first

Run mdls -name kMDItemUserTags against two or three files that should be tagged and are not showing up, since that single check separates a lost attribute from a broken index and the fix is different for each. Then open Finder Settings and cut the tag list down to the names that are actually used. If the slow part turns out to be what happens after the search rather than the search itself, that gap is what Atriens was built to close.