How macOS actually works

The characters filenames cannot carry

Updated 2026-08-08 · 4 min read

macOS itself allows nearly any character in a filename — which is the problem. The file is legal here and illegal on Windows, on SMB shares, and in half the cloud services, and the failure arrives later as a sync error on a file you named two years ago.

What macOS itself forbids

Two things only: the colon, reserved as the ancient path separator, and the null character. Everything else — question marks, asterisks, emoji, newlines if you try hard enough — is a legal APFS filename.

The colon-slash trick

Type a / in a Finder filename and it works; look at the same file in Terminal and it shows a :. The two characters are swapped between layers — Finder displays colons as slashes because slash is the Unix separator and colon was the classic Mac one. Harmless, until a script meets the colon it did not expect.

What everything else forbids

The practical limit is not macOS but everywhere your files travel:

Character(s)	Breaks on
`\ / : * ? " < >	`	Windows, SMB network shares
Leading/trailing spaces, trailing dots	Windows
# and %	Some web upload and sync systems
Emoji, uncommon Unicode	Old systems, some sync services

Cloud services enforce roughly the Windows list: OneDrive refuses the characters outright, Dropbox flags them, iCloud tolerates most but other devices then disagree about the name.

The safe alphabet

Letters, digits, hyphen, underscore, one dot before the extension. Dull, and it has never broken anywhere:

2026-08-08_client-invoice_v2.pdf

Finding the problem files you already have

A sync tool's error list names them one at a time. Wholesale is better — every filename containing Windows-hostile characters:

find ~/Documents -name '*[<>:"\|?*]*'

Renaming a folder's worth is Finder's batch rename (select all → right-click → Rename) with Replace Text, one pass per offending character.

Common questions

Why does a slash in a filename become a colon?

Finder and Terminal swap the two separator characters between display layers. Both refer to the same file; scripts see the colon.

Which characters are safest for cross-platform filenames?

Letters, numbers, hyphens and underscores. Everything beyond that works somewhere and fails somewhere else.