How file systems handle names, across Windows, macOS and Linux

Why three operating systems disagree about a filename

None of this is arbitrary, and none of it is a bug. Each system inherited its rules from a different decade and a different set of constraints, and then kept them for compatibility.

Windows still carries MS-DOS with it. Drive letters, the backslash separator and the reserved device names CON, NUL, COM1 and the rest were decisions made in 1981, when a filename was eight characters and a three-letter extension. Every one of them is still enforced today, because breaking them would break software that has shipped for forty years.

Linux comes from Unix, where a filename is simply a sequence of bytes. Exactly two values are forbidden: the forward slash, because it separates path components, and the null byte, because it ends a C string. Everything else is legal, including newlines, quotes and a leading dash. The system does not interpret your filename at all, which is both the freedom and the hazard.

macOS is Unix underneath with a different history above it. It has always been case-insensitive by default, and older Macs rewrote filenames into a decomposed Unicode form on disk, so a name typed one way came back with different bytes. That single design choice is still the most common source of duplicate files when work moves between a Mac and anything else.

What a file system actually decides

Underneath the differences, every system is answering the same five questions. Once you know which answer each one gives, the table below stops being a list of exceptions and becomes predictable.

• Which characters a name may contain, and whether a forbidden one is refused or silently replaced.
• How long a name and a path may be, and whether the limit counts characters or bytes. That distinction matters enormously once a name is not plain English.
• Whether case matters. On one system README and readme are two files; on another they are the same file, and the second one overwrites the first.
• How text is normalised. Unicode can spell the same accented character more than one way, and systems disagree about whether to store what you typed or convert it.
• What a path looks like: which separator, whether there is a root or a drive, and what happens at the boundary between them.

Why it comes up constantly

A file today rarely stays where it was made. It gets committed to a repository on a laptop and checked out in a Linux container, uploaded through a browser and written to object storage, zipped on one machine and extracted on another, or synced through a service that has its own rules on top. Every one of those boundaries is a translation, and translations lose things.

The failures are rarely loud. A name comes back subtly altered, two files collapse into one, an extraction stops part-way through, or a filename matches in testing and not in production. The table below is a map of where those translations go wrong, and each row links to a real file you can download and push through your own code to see which behaviour you actually have.