rsync Commands

Basic Copy

-a (archive) is the flag you almost always want: recursive, keeps permissions, times, owner, group, symlinks, and devices. The rsync command builder assembles one of these interactively.

rsync -a with no -v prints nothing on success, which is what you want in cron.

Trailing Slash

The one thing about rsync that catches everyone, and the reason behind most "it copied into the wrong folder" and "--delete wiped my directory" reports. A trailing slash on the source path means "the contents of this directory". No slash means "this directory itself". The slash on the destination changes nothing at all.

Read src/ as src/* including hidden files, and src as "put a copy of this directory in there". Three consequences worth knowing before you run anything else on this page:

• With --delete, src/ dest/ prunes everything in dest, while src dest/ only prunes dest/src and leaves the rest of dest alone. Getting that backwards is how people empty a directory.
• Tab completion appends the slash for you, so the command you typed and the command you tabbed are not the same command. Check the source path before pressing Enter, and dry run with -n.
• src/ is not the same as src/*. The glob is expanded by the shell, which skips dotfiles, so rsync -av src/* dest/ silently leaves out .env and .htaccess.

Over SSH

Remote paths are user@host:/path. rsync must be installed at both ends. It runs over SSH by default, so keys, ~/.ssh/config aliases, and agent forwarding all apply; see the SSH cheat sheet.

Copy between two remote servers: rsync cannot take two remote paths in one command. Log into one and push to the other, or forward your agent so the first server can authenticate to the second.

ssh -A user@server1 'rsync -avz /var/www/ user@server2:/var/www/'

A connection that fails with exit code 255 is an SSH problem, not an rsync one. See Connection refused and Permission denied (publickey).

Flags Explained

Paste any command into the rsync flag explainer to decode it.

-avz is the standard remote copy, -avh the standard local one, and -avzP when the link might drop.

Dry Run

Run every new rsync command with -n first, and always before --delete.

In itemized output, >f is a file being sent, cd a directory being created, *deleting a deletion, and the dots after the type mark which attributes changed (s size, t time, p permissions, o owner).

Exclude and Include

Patterns match relative to the top of the transfer. A trailing / matches directories only, a leading / anchors the pattern to the transfer root, and * does not cross a / (** does).

Include and exclude rules are checked in order and the first match wins, which is why --include comes before --exclude '*'. An exclude that "does not work" is almost always anchored wrong: --exclude 'src/node_modules' does not match when the transfer root is src/, but --exclude '/node_modules' does.

Delete and Mirror

--delete makes the destination match the source exactly, including removing files. Combined with a wrong path or a missing trailing slash it can empty a directory, so dry run first.

--delete only deletes inside directories that are part of the transfer. rsync -av --delete src dest/ (no trailing slash) syncs dest/src/ and never touches the rest of dest.

Progress and Resume

For a transfer that takes hours, start it inside tmux or screen so a dropped SSH session does not kill it; see the tmux cheat sheet. If the SSH session itself keeps dropping, see Broken pipe.

Speed and Large Transfers

One rsync run is single-threaded and uses one SSH connection, so the way to go faster is usually to do less work or to run several transfers at once.

On trees with hundreds of thousands of small files, building and comparing the file list costs more than the transfer, and no flag fixes that. Split the tree and run several rsyncs, or tar the directory and copy one stream.

Compare and Verify

rsync decides what to send from size and modification time, not from file contents. These commands compare without copying, or force a content comparison.

rsync already checksums every file it transfers and retries any that fails, so a run that exits 0 wrote correct data. -c is about deciding what to send, not about verifying what arrived.

Permissions and Ownership

Preserving owner means rsync on the receiving end runs as root, either because you are root or via --rsync-path="sudo rsync". Otherwise files are owned by the connecting user and rsync prints nothing about it.

Backups and Snapshots

--link-dest is what turns rsync into a backup tool: each run is a full dated tree, but files that did not change are hard links to the previous run and cost no extra disk. The rsync command builder has a link-dest field if you would rather assemble the command than type it.

A hard-linked snapshot set shares inodes, so every snapshot of an unchanged file is the same blocks on the same disk. It protects against deleting a file, not against the drive dying. Keep one copy on another machine.

Cron and Logging

In cron there is no terminal, no ssh-agent, and a minimal PATH, which is where nearly every "works by hand, fails in cron" report comes from.

# /etc/cron.d/backup
0 3 * * * root /usr/bin/flock -n /var/lock/backup.lock /usr/bin/rsync -a --delete \
  -e "ssh -i /root/.ssh/backup_key -o BatchMode=yes" /srv/ backup@host:/srv/ \
  >> /var/log/backup.log 2>&1

Use absolute paths, a key with no passphrase (or a systemd timer with the agent available), and check $? rather than the output: rsync -a prints nothing on success, so a silent cron job and a failed one look the same. BatchMode=yes turns a password prompt into an immediate exit 255, which is the behaviour you want when nobody is watching.

Daemon Mode

rsync can also run as its own service on TCP 873, with no SSH and no encryption. Remote paths then use a double colon or an rsync:// URL, and the first component is a module name from rsyncd.conf, not a filesystem path.

# /etc/rsyncd.conf
[backup]
path = /srv/backup
read only = false
auth users = deploy
secrets file = /etc/rsyncd.secrets
hosts allow = 10.0.0.0/24

One colon means SSH, two colons mean the daemon. Mixing them up gives unexpected remote arg or a hang on port 873. Daemon traffic is plaintext and the passwords are not SSH keys, so keep it on a private network and use the default SSH transport over the internet.

Common Recipes

Back up a home directory to an external drive:

rsync -avh --delete --exclude '.cache/' --exclude 'node_modules/' ~/ /Volumes/Backup/home/

Mirror a website from a server, keeping a rotating set of dated snapshots that share unchanged files via hard links:

rsync -avz --delete --link-dest=/backup/www/latest user@host:/var/www/ /backup/www/$(date +%F)/
ln -sfn /backup/www/$(date +%F) /backup/www/latest

Deploy a build, excluding what should not ship, then reload:

rsync -avz --delete --exclude '.git' --exclude '.env' --exclude 'node_modules' \
  ./dist/ deploy@host:/var/www/app/ && ssh deploy@host 'sudo systemctl reload nginx'

Copy only files changed in the last day:

find src -type f -mtime -1 -printf '%P\n' | rsync -av --files-from=- src/ dest/

Sync two directories both ways (run once in each direction; rsync is one-way, --update keeps the newer copy):

rsync -avu a/ b/ && rsync -avu b/ a/

Move a whole server's data directory to a new host over a slow link, resumable:

rsync -avzP --bwlimit=20m -e "ssh -p 2222" /srv/data/ root@newhost:/srv/data/

Clone a disk or root filesystem to another mounted volume, staying off /proc, /sys, and other mounts:

sudo rsync -aAXHvx --numeric-ids --exclude={'/dev/*','/proc/*','/sys/*','/tmp/*','/run/*','/mnt/*','/media/*','/lost+found'} / /mnt/newdisk/

Windows and macOS

rsync is a Unix program. Windows has no native version, and the one Apple ships is not the rsync the manual describes.

Check which one you have with rsync --version. Under WSL, a copy from /mnt/c cannot preserve Unix permissions, so expect -a to warn and use --no-perms --no-owner --no-group there too.

rsync vs scp

OpenSSH's scp has used the SFTP protocol under the hood since 9.0, which fixed its security problems but did not add any of the above.

Two other comparisons come up often. rclone is the tool when one side is cloud storage (S3, Google Drive, OneDrive, Backblaze), which rsync cannot speak at all. robocopy is the Windows built-in that mirrors local and SMB paths with /MIR, but has no SSH transport and no delta algorithm.

Exit Codes

rsync reports its result in the exit code (echo $? right after it runs), which is what a cron job or a script should check.

Gotchas

• --delete with the wrong trailing slash or a mistyped destination removes real files. -n first, every time.
• rsync must exist on the remote host. bash: rsync: command not found from the far end and exit code 12 or 127 mean apt install rsync there, not here.
• A .bashrc on the remote that prints something (a banner, a echo, an unguarded neofetch) corrupts the protocol stream and gives protocol version mismatch or code 12. Guard it with [[ $- != *i* ]] && return at the top.
• macOS ships an old rsync 2.6.9, and macOS 15 replaced it with openrsync, which lacks flags such as --info=progress2. brew install rsync gives you 3.x; on Windows, rsync comes with WSL, Cygwin, or MSYS2, not with Git Bash by default.
• -z slows down a LAN copy and does nothing for files that are already compressed (images, video, archives). Use it over the internet, drop it locally.
• Copying to a drive formatted exFAT, FAT32, or NTFS from Linux recopies everything each run because the filesystem cannot store the same times and permissions. Add --no-perms --no-owner --no-group --modify-window=1 or --size-only.
• rsync -av src/*.jpg dest/ dies in zsh with zsh: no matches found when nothing matches, because zsh refuses an unmatched glob instead of passing it through the way bash does. Pick files with --include '*.jpg' --exclude '*' rather than a shell glob. On a remote source the glob is expanded by the remote shell, so it has to be quoted: rsync -av 'user@host:/var/log/*.gz' ./.
• unexpected remote arg means the remote path is missing its colon (user@host/path instead of user@host:/path) or you gave two remote paths in one command.
• Changing only a file's permissions or owner does not change its size or time, so a plain -av run does not resend it but does update the attributes. Content edits that keep the same size and time (rare, but touch -r and some build tools do it) need -c to be noticed.