You receive a ZIP archive from a colleague on macOS, extract it on Windows, and half the files are missing. A script written on Windows produces garbled output on Linux. A video plays fine on one machine and shows a black screen on another. Cross-platform file compatibility is a minefield of subtle differences that only surface when files move between operating systems.
Most of these issues have been known for decades, and most have straightforward solutions. The problem is that nobody encounters them until they're already frustrated. This guide catalogues every major cross-platform compatibility issue with file formats, explains why each one exists, and tells you how to fix or avoid it.
These aren't theoretical problems. If you collaborate with anyone using a different OS — and in 2026, you certainly do — you'll hit at least one of these issues this month.
Filename Incompatibilities
Case Sensitivity
Linux: Fully case-sensitive. Report.pdf, report.pdf, and REPORT.PDF are three different files in the same directory. This is an ext4/XFS filesystem property, not a kernel requirement.
macOS: Case-insensitive but case-preserving by default (HFS+/APFS). Report.pdf and report.pdf refer to the same file. The filesystem remembers the original casing but treats lookups as case-insensitive.
Windows: Case-insensitive, case-preserving (NTFS). Same behavior as macOS — Report.pdf and REPORT.PDF are the same file.
The problem: a Git repository or ZIP archive created on Linux can contain both utils.js and Utils.js. Extract that archive on Windows or macOS and one file silently overwrites the other. This is the single most common cross-platform issue in software development.
Special Characters and Reserved Names
Windows forbids these characters in filenames: \ / : * ? " < > |. It also reserves names regardless of extension: CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9. A file named aux.txt on Linux cannot exist on Windows. A file with a colon in its name (common in macOS Finder timestamps like Screenshot 2026-03-19 at 14:30:22.png) fails on Windows.
macOS forbids only / and the null byte. Linux forbids only / and null. This means filenames that are perfectly legal on Unix systems — like file:name, my*project, or notes|draft — will cause extraction failures on Windows.
Path Length Limits
Windows traditionally limits full paths to 260 characters (MAX_PATH). Since Windows 10 version 1607, long paths can be enabled via Group Policy, but many applications still hit the 260-character wall. Deeply nested node_modules directories are the classic example — a path like C:\project\node_modules\package\node_modules\dep\node_modules\sub\... can easily exceed 260 characters.
macOS limits filenames to 255 bytes (HFS+) or 255 UTF-8 characters (APFS). Linux limits filenames to 255 bytes and full paths to 4096 bytes (PATH_MAX). When extracting archives with deep paths, Windows is by far the most likely to fail.
Line Endings: CRLF vs LF
This one dates to the teletype era. Windows uses \r\n (Carriage Return + Line Feed, hex 0D 0A) to end lines. Unix/Linux/macOS use \n (Line Feed only, hex 0A). Classic Mac OS (pre-OS X) used \r alone, but that's been dead since 2001.
Why it matters: open a Windows-created text file on Linux and you may see ^M characters at the end of every line. Open a Linux-created script on Windows Notepad (pre-2018) and the entire file appears as one line. Modern text editors handle both gracefully, but programming tools are less forgiving:
- Bash scripts with CRLF line endings fail with
/bin/bash^M: bad interpreter - Makefiles with CRLF produce "missing separator" errors
- CSV files with mixed line endings confuse parsers
- Git diffs show every line as changed when line endings differ
Fix: use dos2unix / unix2dos to convert, or configure Git's core.autocrlf setting. For files you're sharing cross-platform, LF is the safer default — Windows tools handle LF better than Unix tools handle CRLF. When converting text-based files like CSV to JSON or XML to YAML, most converters normalize line endings automatically.
Character Encoding: The UTF-8 Migration
Windows historically used Windows-1252 (a superset of ISO-8859-1/Latin-1) as its default text encoding. Linux and macOS have used UTF-8 as the system default since the early 2000s. This mismatch causes garbled text — curly quotes become “ rendered as mojibake, em-dashes become — as garbled bytes, and accented characters become multi-character garbage.
Common scenarios:
- A CSV exported from Excel on Windows (Windows-1252) opened on macOS shows corrupted accented characters
- A Python script saved as UTF-8 on Linux has a BOM (Byte Order Mark) issue when opened on Windows
- A JSON file with Windows-1252 smart quotes fails to parse because JSON requires UTF-8
Windows has been moving toward UTF-8. Since Windows 10 version 1903, there's a "Use UTF-8 for worldwide language support" setting under Region → Administrative → Change system locale. Notepad defaulted to UTF-8 for new files starting in Windows 11. But legacy applications and older files remain Windows-1252.
The rule: always save text files as UTF-8 without BOM. This is universally compatible. When converting structured data formats (CSV to JSON, XML to JSON), specify UTF-8 encoding explicitly to avoid garbled output.
Archive and Compression Issues
Archives are a major source of cross-platform pain because they preserve (or fail to preserve) OS-specific file attributes.
ZIP Path Separators and Encoding
The ZIP specification (PKWARE APPNOTE) requires forward slashes (/) for path separators. Most tools comply, but some Windows archivers use backslashes (\), which Unix tools may treat as literal characters in filenames — creating a file literally named folder\file.txt instead of folder/file.txt.
Filename encoding in ZIP is another headache. The original ZIP format used IBM Code Page 437. The 2006 APPNOTE update added a UTF-8 flag (bit 11 of the general purpose bit flag), but older archives and older tools don't set or check it. A ZIP created on a Japanese Windows system with Shift-JIS filenames will show garbled names everywhere else. Converting to tar.gz with explicit UTF-8 encoding can fix this.
Unix Permissions and Symlinks
TAR archives preserve Unix permissions (rwx), ownership (uid/gid), and symbolic links. ZIP partially supports them via the "external file attributes" field, but it's inconsistent — Windows ZIP tools typically don't set Unix permission bits, so extracting a ZIP on Linux may produce files without execute permission even if they're scripts.
Conversely, TAR archives with symlinks extracted on Windows fail entirely — Windows doesn't support Unix-style symlinks in the same way (NTFS has junction points, which are different). A TAR containing symlinks should be converted to a flat archive format on Windows.
The safest cross-platform archive formats: ZIP for Windows-centric sharing (universal support, no permission headaches), TAR.GZ for Unix-centric sharing (preserves permissions), 7Z for maximum compression (handles Unicode filenames well).
Document Rendering Differences
Send a DOCX from Microsoft Word on Windows to LibreOffice on Linux and expect layout differences. They use different text rendering engines, different default fonts, and different interpretations of the OOXML specification (which is 7,000+ pages and deliberately ambiguous in places).
Common issues:
- Font substitution: Calibri (Word's default since 2007) isn't installed on Linux. LibreOffice substitutes a similar font, but metrics differ — line breaks shift, pages reflow, tables misalign.
- Spacing and kerning: Windows ClearType and macOS font rendering produce different glyph widths. A document that fits on one page in Word may spill to two pages in LibreOffice.
- Embedded objects: OLE objects (embedded Excel charts, Visio diagrams) may not render in LibreOffice at all.
- Macros: VBA macros don't run outside Microsoft Office. LibreOffice has partial VBA compatibility but it's unreliable for complex macros.
The solution for documents that must look identical everywhere: convert to PDF. PDF embeds fonts and fixes layout, making it the universal cross-platform document format. For editable documents, DOCX to ODT works when both parties use LibreOffice.
Video Playback and Codec Availability
A video file is a container (MP4, MKV, AVI) holding compressed streams. Whether it plays depends on whether the OS has decoders for those specific codecs.
| Codec | Windows | macOS | Linux |
|---|---|---|---|
| H.264 | Built-in | Built-in | Requires install (often included in distros) |
| H.265/HEVC | $0.99 from MS Store (or free via device manufacturer) | Built-in (since High Sierra) | Requires install |
| AV1 | Built-in (since Win 11) | Built-in (since Ventura) | Requires install |
| VP9 | Built-in | Built-in (since Big Sur) | Usually included |
| ProRes | Not supported natively | Built-in | Requires FFmpeg |
| WMV/WMA | Built-in | Not supported natively | Requires install |
The safest cross-platform video format: MP4 container with H.264 video and AAC audio. This combination plays on every OS, every browser, and every smartphone without installing anything. If you have a video in another format, convert MKV to MP4, AVI to MP4, or WMV to MP4.
Hidden Files and OS-Specific Junk
macOS creates .DS_Store files in every directory (Finder view settings) and ._ resource fork files (extended attributes stored as separate files on non-HFS filesystems). ZIP archives created on macOS include the __MACOSX directory containing these resource forks. Windows users see this mysterious folder and wonder what it is.
Windows creates Thumbs.db (thumbnail cache) and desktop.ini (folder view settings) in directories. These are hidden on Windows but visible on Linux/macOS.
Linux creates no such junk files at the OS level, though applications may create .directory files (KDE) or other dotfiles.
When creating archives to share cross-platform, exclude these: zip -x "*.DS_Store" -x "__MACOSX/*" -x "Thumbs.db". Or convert archives between formats — ZIP to TAR.GZ tools typically offer options to filter OS metadata.
Cross-platform compatibility isn't a single problem — it's a collection of historical decisions made independently by Microsoft, Apple, and the Linux community over four decades. Each decision made sense in isolation (case-insensitive filenames are user-friendly; CRLF made sense for teletypes) but creates friction when files cross boundaries.
The safest approach: use universally compatible formats (PDF for documents, MP4 for video, UTF-8 for text, ZIP for archives), avoid special characters in filenames, and test your files on the recipient's platform before sending anything important. When in doubt, convert to the most widely supported format available.