Comprehensive Guide to the rsync Command in Linux

The rsync command is a powerful and versatile utility for synchronizing files and directories between two locations, either locally or remotely, on Linux, macOS, and other Unix-like systems. It’s widely used for backups, mirroring, and efficient file transfers due to its incremental transfer capabilities, speed, and flexibility. This guide provides a comprehensive overview of the rsync command, covering its syntax, options, practical examples, and advanced use cases, tailored for both beginners and advanced users as of August 15, 2025. The information is based on the latest rsync version (3.3.0) and common Linux distributions like Ubuntu 24.04.

What is the rsync Command?

rsync (remote sync) is a command-line tool that synchronizes files and directories between two locations, minimizing data transfer by copying only the differences between source and destination. Key features include:

• Incremental Backups: Transfers only changed portions of files, saving bandwidth and time.
• Local and Remote Sync: Works locally or over SSH/SCP for remote servers.
• Preservation: Maintains file permissions, timestamps, ownership, and symbolic links.
• Flexibility: Supports compression, exclusions, deletions, and dry runs.

Common use cases:

• Backing up data to external drives or remote servers (e.g., Hetzner Storage Boxes).
• Mirroring websites or repositories.
• Synchronizing development environments across machines.

Prerequisites

• Operating System: Linux (e.g., Ubuntu 24.04), macOS, or Unix-like system.
• Access: rsync installed (pre-installed on most Linux distributions; macOS may require Homebrew).
• Permissions: Read access to source files and write access to the destination.
• Network: For remote sync, SSH access and open port 22.
• Optional: SSH key for passwordless authentication.

Verify rsync installation:

rsync --version

Install if missing:

• Ubuntu/Debian:

  sudo apt-get update
  sudo apt-get install -y rsync

• macOS (Homebrew):

  brew install rsync

Syntax of the rsync Command

The general syntax is:

rsync [OPTION]... SRC [SRC]... DEST

• OPTION: Flags to customize behavior (e.g., -a, --progress).
• SRC: Source file(s) or directory (local or remote, e.g., /home/user/data or user@host:/path).
• DEST: Destination path (local or remote).

For remote transfers, use SSH:

rsync [OPTION]... SRC user@host:DEST

or

rsync [OPTION]... user@host:SRC DEST

Common Options

Below are key rsync options, based on the rsync man page for version 3.3.0:

Option	Description
-a, --archive	Archive mode: recursive, preserves permissions, timestamps, symlinks, etc.
-v, --verbose	Increase verbosity, showing detailed output.
-r, --recursive	Copy directories recursively (included in -a).
-z, --compress	Compress data during transfer to save bandwidth.
-P	Combines --progress (show transfer progress) and --partial (keep partially transferred files).
--progress	Display progress during transfer.
--delete	Delete files in the destination that no longer exist in the source.
--exclude=PATTERN	Exclude files matching PATTERN (e.g., *.tmp).
--include=PATTERN	Include files matching PATTERN (used with --exclude).
-e, --rsh=COMMAND	Specify the remote shell (e.g., ssh -p 22).
--dry-run	Simulate the transfer without making changes.
--bwlimit=RATE	Limit bandwidth usage (in KB/s).
-u, --update	Skip files that are newer in the destination.
--times, -t	Preserve modification times (included in -a).
--perms, -p	Preserve permissions (included in -a).
--size-only	Skip files with same size, ignoring timestamps.
--checksum	Compare files by checksum instead of size/timestamp.
--log-file=FILE	Log output to a file.
--help	Display help information.
--version	Show version information.

Practical Examples

Below are common and advanced use cases for rsync, with examples.

1. Local Directory Sync

Sync a local directory (/home/user/data) to another (/backup):

rsync -avh --progress /home/user/data/ /backup/

• -a: Preserve permissions, timestamps, etc.
• -v: Show verbose output.
• -h: Human-readable sizes.
• --progress: Show transfer progress.
• Note the trailing / on data/ to sync contents, not the directory itself.

2. Remote Sync to a Server

Back up a local directory to a remote server (e.g., Hetzner Storage Box):

rsync -avh --progress -e 'ssh -p 23' /home/user/data/ [email protected]:backups/

• -e 'ssh -p 23': Use SSH on port 23 (Hetzner’s default for Storage Boxes).
• Replace uXXXXXX with your username and server address.

3. Remote Sync from a Server

Pull files from a remote server to a local directory:

rsync -avh --progress -e 'ssh -p 22' [email protected]:/var/www/html/ /local/backup/

4. Exclude Files or Directories

Exclude temporary files and logs:

rsync -avh --progress --exclude '*.tmp' --exclude 'logs/' /home/user/data/ /backup/

Use multiple excludes:

rsync -avh --exclude-from='exclude-list.txt' /home/user/data/ /backup/

exclude-list.txt example:

*.tmp
logs/
cache/

5. Delete Files Not in Source

Remove files in the destination that no longer exist in the source:

rsync -avh --delete /home/user/data/ /backup/

Warning: Use --dry-run first to preview deletions:

rsync -avh --delete --dry-run /home/user/data/ /backup/

6. Limit Bandwidth

Cap transfer speed to 1 MB/s:

rsync -avh --bwlimit=1000 /home/user/data/ /backup/

7. Compress During Transfer

Reduce bandwidth usage:

rsync -avhz /home/user/data/ [email protected]:/backup/

8. Sync Specific Files

Sync only .jpg files:

rsync -avh --include '*.jpg' --exclude '*' /home/user/photos/ /backup/

9. Preserve Hard Links and Sparse Files

For advanced use cases (e.g., backups):

rsync -avhH --sparse /home/user/data/ /backup/

• -H: Preserve hard links.
• --sparse: Handle sparse files efficiently.

10. Automate with a Script

Create a backup script (backup.sh):

#!/bin/bash
rsync -avh --progress --delete --exclude '*.tmp' /home/user/data/ [email protected]:backups/
if [ $? -eq 0 ]; then
    echo "Backup completed successfully!"
else
    echo "Backup failed!" >&2
fi

Run it:

chmod +x backup.sh
./backup.sh

11. Schedule with Cron

Run daily backups at 2 AM:

crontab -e

Add:

0 2 * * * rsync -avh --delete --exclude '*.tmp' /home/user/data/ [email protected]:backups/ >> /var/log/backup.log 2>&1

12. Use with SSH Key

Set up passwordless SSH:

ssh-keygen -t ed25519 -f ~/.ssh/rsync_key
ssh-copy-id -i ~/.ssh/rsync_key -p 23 [email protected]

Sync without password prompt:

rsync -avh -e 'ssh -i ~/.ssh/rsync_key -p 23' /home/user/data/ [email protected]:backups/

13. Mirror a Website

Mirror a remote website to a local directory:

rsync -avh --delete user@webserver:/var/www/html/ /local/mirror/

14. Log Output

Save transfer logs:

rsync -avh --log-file=/var/log/rsync.log /home/user/data/ /backup/

Advanced Use Cases

• Incremental Backups with Timestamps:
  Use --link-dest for hard-linked incremental backups:

  rsync -avh --delete --link-dest=/backup/2025-08-14 /home/user/data/ /backup/2025-08-15

This links unchanged files to the previous backup, saving space.

• Sync with Compression and Encryption:
  Combine with gzip and SSH:

  tar -czf - /home/user/data | rsync -avh -e 'ssh -p 22' --progress - /backup/compressed.tar.gz

• Exclude Based on Size:
  Skip files larger than 100 MB:

  rsync -avh --max-size=100m /home/user/data/ /backup/

• Sync with Include/Exclude Patterns:
  Sync only .pdf and .docx files:

  rsync -avh --include '*.pdf' --include '*.docx' --exclude '*' /home/user/docs/ /backup/

• Verbose Debugging:
  Increase verbosity for troubleshooting:

  rsync -avv --stats /home/user/data/ /backup/

Troubleshooting Common Issues

• Permission Denied:
• Check file permissions (ls -l) and SSH credentials.
• Use sudo for local files or verify remote user access.

  sudo rsync -avh /root/data/ /backup/

• Connection Refused:
• Ensure SSH port is open (e.g., telnet remote.host 22).
• Verify firewall settings or Hetzner Console SSH settings.
• Slow Transfers:
• Use --bwlimit to throttle:
  bash rsync -avh --bwlimit=500 /home/user/data/ /backup/
• Enable compression (-z).
• Files Skipped Unexpectedly:
• Check --exclude patterns or use --dry-run to preview.
• Verify timestamps with -t or use --checksum.
• Log Rotation Issues:
• Use --noatime to avoid updating access times: rsync -avh --noatime /home/user/data/ /backup/
• Error Codes:
• Check rsync exit codes (man rsync for details). Common codes:
  • 0: Success
  • 23: Partial transfer due to error
  • 30: Timeout
• Example:
  bash rsync -avh /home/user/data/ /backup/ echo $?

Performance Considerations

• Incremental Transfers: rsync’s delta algorithm minimizes data transfer.
• Compression: Use -z for remote transfers over slow networks.
• Bandwidth: Use --bwlimit to avoid network congestion.
• Large Files: Enable --partial to resume interrupted transfers.
• CPU Usage: For large directories, use --checksum sparingly as it’s CPU-intensive.

Security Considerations

• SSH Keys: Use SSH keys for secure, passwordless transfers.
• Encryption: For sensitive data, encrypt locally before transfer (e.g., with gpg).
• Permissions: Restrict destination directory access to prevent unauthorized changes.
• Logging: Avoid logging sensitive data with --log-file.

Alternatives to rsync

• scp: Simple file copying over SSH, less flexible.
• Restic: Encrypted, deduplicated backups (see previous guide).
• **tar`: For archiving before transfer.
• SimpleBackups: Managed backup service for automation.

Conclusion

The rsync command is an essential tool for efficient file synchronization and backups, offering unmatched flexibility for local and remote transfers. With options like -a, --delete, and --exclude, it’s ideal for tasks from simple backups to complex mirroring. By combining rsync with SSH, cron, or scripts, you can automate robust backup solutions, as shown with Hetzner Storage Boxes. For further details, consult man rsync or rsync --help, and test commands with --dry-run to avoid errors.

Note: Based on rsync 3.3.0 and Ubuntu 24.04 as of August 15, 2025. Verify options with rsync --help for your system’s version.