Compatibility Issues
Rsync runs on Linux, macOS, BSD, and Windows (via WSL/Cygwin), but differences in rsync versions, filesystem features, and OS behavior can cause unexpected failures during cross-platform transfers.
Version Compatibility
Check Versions on Both Sides
# Local version
rsync --version | head -1
# Remote version
ssh user@remote "rsync --version | head -1"
Version Feature Matrix
| Feature | Minimum Version | Notes |
|---|---|---|
--info=FLAGS | 3.1.0 | Fine-grained output control |
--compress-choice | 3.2.0 | Choose compression algorithm |
--debug=FLAGS | 3.1.0 | Detailed debug output |
--checksum-choice | 3.2.0 | Choose hash algorithm |
| Incremental file list | 3.0.0 | Sends file list progressively |
--iconv | 3.0.0 | Filename charset conversion |
-AX (ACLs + xattrs) | 2.6.7 | Must be compiled with support |
Force Protocol Version
When client and server run different rsync versions:
# Use an older protocol version for compatibility
rsync -av --protocol=29 /src/ user@older-server:/dest/
tip
Check supported protocols: rsync --version shows the protocol version.
Operating System Differences
macOS → Linux
macOS uses HFS+/APFS which handles metadata differently from ext4:
# Skip macOS-specific extended attributes
rsync -av --no-xattrs /src/ user@linux-server:/dest/
# Also skip resource forks (macOS ._ files)
rsync -av --no-xattrs --exclude='._*' --exclude='.DS_Store' \
/src/ user@linux-server:/dest/
Windows → Linux (via WSL)
# Convert filename encoding
rsync -av --iconv=CP1252,UTF-8 /mnt/c/project/ user@linux:/var/www/html/
# Windows doesn't support Unix permissions — set them on destination
rsync -av --chmod=D755,F644 /mnt/c/project/ user@linux:/var/www/html/
warning
--iconv converts filename encoding only, not file contents. For line-ending conversion, use dos2unix or unix2dos before syncing.
Linux → Linux (Different Distros)
Usually seamless, but watch for:
# Full metadata preservation (both must support ACLs + xattrs)
rsync -avAX /src/ user@remote:/dest/
# If destination doesn't support ACLs, skip them
rsync -av --no-acls /src/ user@remote:/dest/
Filesystem Compatibility
| Filesystem | Permissions | Symlinks | ACLs | xattrs | Case-Sensitive |
|---|---|---|---|---|---|
| ext4 | Full | ||||
| XFS | Full | ||||
| ZFS | Full | ||||
| Btrfs | Full | ||||
| HFS+ (macOS) | Limited | Resource forks | |||
| APFS (macOS) | Limited | Configurable | |||
| NTFS | Partial | ||||
| FAT32 | |||||
| NFS | Depends on export | Depends | Depends |
Handling Filesystem Limitations
# Syncing to a filesystem that doesn't support symlinks
rsync -av --copy-links /src/ /mnt/ntfs-drive/backup/
# Converts symlinks to copies of the target files
# Syncing to FAT32/NTFS (no Unix permissions)
rsync -av --no-perms --no-owner --no-group /src/ /mnt/usb-drive/backup/
# Handling case-insensitive filesystems
rsync -av --no-implied-dirs /src/ /mnt/hfs-volume/backup/
Character Encoding Issues
Non-ASCII Filenames
# Check for problematic filenames
find /src/ -name '*[^a-zA-Z0-9._/-]*' -print
# Convert filenames during transfer
rsync -av --iconv=UTF-8,UTF-8 /src/ user@remote:/dest/
# Log files with encoding issues
rsync -avv --iconv=UTF-8,UTF-8 /src/ user@remote:/dest/ 2>&1 | grep "iconv"
Pre-Migration Compatibility Check
Before a large migration, run this checklist:
#!/bin/bash
# compatibility-check.sh — Run before migration
echo "=== Local System ==="
rsync --version | head -1
uname -a
stat -f /src/ 2>/dev/null || stat --file-system /src/ 2>/dev/null
echo ""
echo "=== Remote System ==="
ssh user@remote "rsync --version | head -1"
ssh user@remote "uname -a"
ssh user@remote "stat -f /dest/ 2>/dev/null || stat --file-system /dest/ 2>/dev/null"
echo ""
echo "=== Test Transfer ==="
rsync -avn --itemize-changes /src/ user@remote:/dest/ 2>&1 | head -20
Common Pitfalls
| Pitfall | Consequence | Prevention |
|---|---|---|
Using -AX with NTFS/FAT | Error or silently dropped | Use --no-acls for incompatible filesystems |
macOS .DS_Store files | Junk files on server | Exclude --exclude='.DS_Store' |
| Version mismatch | Protocol incompatibility error | Use --protocol=29 or upgrade |
| Case-insensitive destination | File overwrites (e.g., README and readme) | Rename conflicting files before sync |
| Timestamp handling (FAT32) | 2-second granularity | Use --modify-window=2 |
| NFS-mounted destination | Permission/lock issues | Use --no-specials --no-devices |
Quick Reference
# Check versions
rsync --version | head -1
ssh user@remote "rsync --version | head -1"
# Force protocol compatibility
rsync -av --protocol=29 /src/ user@remote:/dest/
# macOS → Linux (clean transfer)
rsync -av --no-xattrs --exclude='._*' --exclude='.DS_Store' /src/ user@linux:/dest/
# Windows → Linux (WSL)
rsync -av --iconv=CP1252,UTF-8 --chmod=D755,F644 /mnt/c/src/ user@linux:/dest/
# Skip features unsupported on destination
rsync -av --no-acls --no-xattrs --no-perms /src/ /mnt/ntfs/dest/
# Symlinks to copies
rsync -av --copy-links /src/ /dest/
# FAT32 timestamp tolerance
rsync -av --modify-window=2 /src/ /mnt/usb/dest/
What's Next
- Troubleshooting and Debugging — Debug specific failures
- Exit Codes and Error Handling — Handle errors in scripts
- Options and Flags — Reference for all rsync flags