Console9

Rsync

Rsync is a file synchronization utility that transfers and syncs files between local and remote systems using delta encoding on Linux, macOS, and Windows (via WSL).

Rsync is a file synchronization utility that transfers and syncs files between local and remote systems on Linux, macOS, and Windows (via WSL or Cygwin).

What Rsync Does and When to Use It

Rsync copies files from a source to a destination while transferring only the bytes that changed. It uses a delta-transfer algorithm that computes rolling checksums on both ends and sends only the differing blocks. A 2 GB file with a 5 KB change results in roughly 5 KB of network transfer.

Rsync operates over Secure Shell (SSH) by default, which encrypts all data in transit. It supports local-to-local, local-to-remote, and remote-to-local transfers. Rsync preserves file permissions, timestamps, symbolic links, and ownership when archive mode ( -a) is enabled.

Rsync is not a real-time synchronization tool. It runs on demand or on a schedule via cron. For real-time file syncing, use tools such as lsyncd or inotifywait paired with Rsync. For one-time, non-recurring file copies where delta transfer is unnecessary, SCP or SFTP may be faster on initial transfers. See the Rsync vs SCP comparisonfor details.

How to Install Rsync

Rsync comes preinstalled on most Linux distributions and macOS. Verify the installation by checking the version number.

rsync --version

Install Rsync if it is not present on the system.

=== "Ubuntu / Debian"

sudo apt update && sudo apt install rsync

=== "CentOS / Fedora / RHEL"

sudo dnf install rsync

=== "macOS (Homebrew)"

brew install rsync

For full installation instructions, see How to Install Rsync.

Core Concepts of Rsync

Rsync Delta-Transfer Algorithm

Rsync computes rolling checksums on the source and destination files. It compares these checksums and transmits only the blocks that differ. This delta-transfer approach reduces bandwidth usage and speeds up repeated transfers of large, infrequently changing files.

Rsync Archive Mode (-a Flag)

Rsync's archive mode ( -a flag) preserves file permissions, timestamps, symbolic links, group ownership, and device files during transfer. The -a flag is equivalent to combining -rlptgoD. Archive mode is the recommended default for most backup and synchronization tasks.

Rsync Dry Run (--dry-run Flag)

Rsync's dry-run mode ( -n or --dry-run flag) simulates the transfer without modifying any files. Dry run shows which files Rsync would copy, skip, or delete. Run every Rsync command with --dry-run first to verify the expected behavior before executing the actual transfer.

Rsync Trailing Slash Behavior

Rsync treats a trailing slash ( /) on the source path as "contents of the directory." Without the trailing slash, Rsync copies the directory itself into the destination. This distinction affects the resulting directory structure at the destination.

# Copies the CONTENTS of src/ into dest/
rsync -av /home/user/src/ /home/user/dest/

# Copies the src directory itself into dest/ (creates dest/src/)
rsync -av /home/user/src /home/user/dest/

Common Tasks with Rsync

How to Copy Files from Local to Remote with Rsync

Rsync transfers a local directory to a remote server over SSH with archive mode, verbose output, and compression enabled.

rsync -avz /home/user/src/ user@203.0.113.10:/home/user/dest/

The -avz flags enable archive mode, verbose output, and compression. Rsync transfers only the changed bytes on subsequent runs. For a full walkthrough, see How to Copy Files with Rsync.

How to Copy Files from Remote to Local with Rsync

Rsync pulls a remote directory to the local machine by reversing the source and destination arguments.

rsync -avz user@203.0.113.10:/home/user/src/ /home/user/dest/

How to Run Rsync Through an SSH Tunnel

Rsync uses SSH as its default remote shell. Specify a non-standard SSH port with the -e flag.

rsync -avz -e "ssh -p 2222" /home/user/src/ user@203.0.113.10:/home/user/dest/

For SSH key authentication setup and advanced tunneling, see How to Run Rsync Through SSH Tunnel.

How to Schedule Rsync with a Cron Job

Rsync runs on a recurring schedule when paired with cron. Add an entry to the crontab to automate incremental backups.

crontab -e

Add the following line to sync every day at 2:00 AM:

0 2 * * * rsync -az /home/user/src/ user@203.0.113.10:/home/user/dest/

For detailed scheduling options, see How to Schedule Rsync via Cron Job.

Rsync Flags and Options Reference

Rsync accepts flags to control transfer behavior, output verbosity, and file handling.

FlagDescriptionDefaultExample
-aArchive mode: preserves permissions, timestamps, symlinks, group, owner, and device files. Equivalent to -rlptgoD.offrsync -a src/ dest/
-vVerbose output: displays file names and transfer summary during the operation.offrsync -av src/ dest/
-zCompresses file data during the transfer to reduce bandwidth usage.offrsync -avz src/ dest/
-nDry run: simulates the transfer without writing any files to disk.offrsync -avn src/ dest/
-PCombines --partial and --progress. Keeps partial files and shows transfer progress.offrsync -avP src/ dest/
-eSpecifies the remote shell to use. Commonly set to ssh or ssh -p PORT.sshrsync -avz -e "ssh -p 2222" src/ dest/
-rRecursive: syncs directories and their contents. Included in -a.offrsync -r src/ dest/
-uUpdate: skips files that are newer on the destination than the source.offrsync -avu src/ dest/
-cChecksum: compares files by checksum instead of modification time and size.offrsync -avc src/ dest/
--deleteDeletes files in the destination that do not exist in the source. Creates an exact mirror.offrsync -av --delete src/ dest/
--excludeExcludes files or directories matching the specified pattern from the transfer.nonersync -av --exclude='*.log' src/ dest/
--bwlimitLimits the transfer bandwidth in kilobytes per second.unlimitedrsync -avz --bwlimit=1000 src/ dest/
--partialKeeps partially transferred files so interrupted transfers can resume.offrsync -av --partial src/ dest/
--progressDisplays a progress bar for each file during the transfer.offrsync -av --progress src/ dest/
--link-destCreates hard links to unchanged files in a reference directory. Used for incremental snapshot backups.nonersync -a --link-dest=/backup/prev src/ /backup/current

For copy-paste-ready command examples, see Rsync Command Snippets.

Rsync Troubleshooting

Rsync produces specific error messages when transfers fail. The table below lists common Rsync errors with links to detailed diagnosis and fix articles.

ErrorCauseFix
failed to set permissions onTarget filesystem (FAT32, NTFS) does not support Unix permissions, or the user lacks ownership of the destination.Full article
failed to set times onDestination directory ownership mismatch, or the filesystem does not support Unix timestamps.Full article
error in rsync protocol data stream (code 12)Disk full on remote machine, Rsync version mismatch, network instability, or missing Rsync installation on the remote host.Full article
Transfer hangs or freezesInsufficient memory, SSH timeout, incorrect Rsync options, or firewall dropping idle connections.Full article

SCP (Secure Copy Protocol) provides a simpler syntax for one-time file transfers but lacks delta-transfer and resume capabilities. See the Rsync vs SCP comparisonfor a detailed feature comparison.

Cron automates recurring Rsync transfers on a schedule. See How to Schedule Rsync via Cron Jobfor setup instructions.

SSH (Secure Shell) provides the encrypted transport layer that Rsync uses by default for remote transfers. See How to Run Rsync Through SSH Tunnelfor configuration details.

© 2026 - Console9