rsync commands

Command lines and options of rsync 3.5.1 from the project's own manual page, grouped by task. Option rows show the single-letter form where one exists and name the long form in the usage text; rows that start with rsync are whole commands printed in the manual. A trailing slash on a source directory copies its contents instead of the directory itself. Batch mode, character-set conversion and protocol tuning are left out.

135 commands in 15 sections. Checked row by row against rsync(1) manual page for rsync 3.5.1 (rsync.1.md at the v3.5.1 release tag, RsyncProject/rsync on GitHub) on . Edited by Jay.

Command forms 7

CommandWhat it does
rsync [OPTION...] SRC... [DEST]Copy between local pathsUsed when no path contains a colon; one source with no destination lists the files instead of copying.
rsync [OPTION...] [USER@]HOST:SRC... [DEST]Pull over a remote shellA single colon after the host selects the remote-shell transport, which is normally ssh.
rsync [OPTION...] SRC... [USER@]HOST:DESTPush over a remote shellrsync has to be installed on both machines; -e picks a shell other than the default.
rsync [OPTION...] [USER@]HOST::SRC... [DEST]Pull from an rsync daemonThe double colon talks to a daemon, typically on TCP port 873, and the first path element is a module name.
rsync [OPTION...] rsync://[USER@]HOST[:PORT]/SRC... [DEST]Pull with an rsync URLReaches the same daemon as the double colon, but the URL can carry a port number itself.
rsync [OPTION...] SRC... [USER@]HOST::DESTPush to an rsync daemonWrites into a daemon module; modules that require authentication ask for a password on connect.
rsync [OPTION...] SRC... rsync://[USER@]HOST[:PORT]/DESTPush with an rsync URLTo contact the daemon directly, leave -e out; with it, rsync starts a daemon through that shell.

Copying directories 8

A trailing slash on the source means the directory's contents; without it the directory itself is created inside the destination. The source directory's attributes are applied in both cases.

CommandWhat it does
rsync -avz foo:src/bar /data/tmpPull a directory by nameWithout a trailing slash the bar directory itself is created, giving /data/tmp/bar, in archive mode with compression.
rsync -avz foo:src/bar/ /data/tmpPull a directory's contentsThe trailing slash on the source puts what is inside bar straight into /data/tmp, with no extra bar level.
rsync -av /src/foo /destCopy a folder into a parentProduces /dest/foo, the same result as the trailing-slash form that names /dest/foo as destination.
rsync -av /src/foo/ /dest/fooCopy contents to a named folderEquivalent to the form without slashes; the attributes of /src/foo are applied to /dest/foo either way.
rsync -av host: /destCopy a host's default directoryA bare host reference needs no trailing slash: the remote default directory's contents land directly in /dest.
rsync -ai foo/ bar/Copy a directory under a new nameThe slash after foo sends only its contents, so they fill bar whatever the destination is called.
rsync -ai src/foo.c save/bar.cCopy a file under a new nameWorks when a single item is sent and save/bar.c is neither an existing directory nor written with a trailing slash.
rsync -ai src/*.c save/dir/Force a destination directoryThe trailing slash stops a wildcard that matches one file from saving it as a file named save/dir.

Copying remote files 6

CommandWhat it does
rsync -t *.c foo:src/Copy matching files to a hostThe shell expands the wildcard; files already on foo are updated by sending only the changed data.
rsync -aiv host:file1 :file2 host:file{3,4} /dest/Pull several remote filesEach further remote source may repeat the host or drop it and start with a bare colon.
rsync -aiv host:'a simple file.pdf' /dest/Pull a filename containing spacesSince 3.2.4 the quoted name reaches the remote side unchanged, with no extra escaping needed.
rsync -aiv host1:dir1 ~/host1-filesPull into a dedicated directoryGiving untrusted remote content its own directory is safer than copying it straight into your home.
rsync -aiz . bkhost:backup/joe/Back up a home directoryThe manual's example for a daily per-user cron job, pushing the current directory to backup/joe on bkhost.
rsync -aiv --remove-source-files rhost:/tmp/{file1,file2}.c ~/src/Move remote files locally--remove-source-files deletes each sent file on rhost once it has arrived, turning the copy into a move.

Paths and recursion 7

CommandWhat it does
-rRecurse into directoriesLong form --recursive; -a includes it, except when --files-from is used.
-dCopy directories without recursingLong form --dirs; a directory's contents come along only when its name is . or ends in a slash.
--mkpathCreate missing destination parentsNormally only the last path component may be missing; this makes all of them, like mkdir -p.
-xStay on one filesystemLong form --one-file-system; recursion stops at mount points, though sources on other filesystems can still be named.
rsync -av /foo/bar/baz.c remote:/tmp/Send a file without its pathOnly the last name element travels, so the remote result is /tmp/baz.c.
rsync -avR /foo/bar/baz.c remote:/tmp/Send a file with its full path-R (--relative) recreates the whole given path remotely, giving /tmp/foo/bar/baz.c.
rsync -avR /foo/./bar/baz.c remote:/tmp/Trim the sent path with /./Only the part after the dot directory is kept, so the file arrives as /tmp/bar/baz.c.

Previewing and output 14

CommandWhat it does
-nDry runLong form --dry-run; pair it with -v or -i to see what a real run would change.
--list-onlyList files instead of copyingImplied when there is one source and no destination; add a destination when listing several sources.
rsync -av --list-only foo* dest/List files matching a wildcardThe destination argument is required because the shell turns foo* into several source arguments.
-vIncrease verbosityOne -v names transferred files plus a summary, two add skipped files; more is meant for debugging.
-qQuiet outputLong form --quiet; suppresses informational messages, including the remote server's, which suits cron jobs.
-iItemize changesLong form --itemize-changes; prints a change summary per file, attribute changes included.
--progressShow progressPrints a progress line for each file as it transfers; it shows nothing useful on a dry run.
rsync -a --info=progress2 src/ dest/Show whole-transfer progressProgress is reported for the entire transfer rather than per file; leaving out -v avoids a scrolling list of names.
--statsPrint transfer statisticsShows how well the delta-transfer algorithm worked, including literal and matched data totals.
-hHuman-readable numbersEach -h raises the level: one gives units of 1000, two give 1024; on its own -h means help.
--out-format=FORMATCustom per-file outputBuilt from %-escapes; with -v and no format set, rsync prints %n%L, the name plus any link target.
--log-file=FILELog activity to a fileOn the client the log uses the format %i %n%L unless --log-file-format sets another.
-VShow version and capabilitiesLong form --version; includes compiled-in features and the default checksum and compression lists.
--helpShow option helpThe short -h works for this only when it is the sole argument.

Preserving attributes 15

CommandWhat it does
-aArchive modeSame as -rlptgoD; ACLs, xattrs, access and create times and hard links still need their own flags.
--no-OPTIONTurn off an implied optionPrefix no- to switch off part of -a, as in --no-perms or --no-D.
-lCopy symlinks as symlinksRecreates each link with its original value; without it, every symlink is skipped with a warning.
-pPreserve permissionsWithout it, existing files keep their permissions and new files get source modes masked by the receiver's umask or default ACL.
-tPreserve modification timesWithout it the next run cannot skip unchanged files and behaves as if -I were given.
-gPreserve groupA receiver not running as super-user can only set groups the receiving user belongs to.
-oPreserve ownerTakes effect only when the receiving rsync runs as super-user; otherwise files belong to the invoking user.
-DPreserve devices and special filesShorthand for --devices --specials; device files are recreated only by a super-user receiver.
-HPreserve hard linksNot part of -a; without it, hard-linked source files arrive as separate copies.
-APreserve ACLsImplies -p, and both systems need compatible ACL entries for it to work.
-XPreserve extended attributesA normal user copies only the user.* namespace; a super-user copies every namespace except system.*.
--chmod=CHMODChange permissions in transitTakes comma-separated modes such as D2775,F664, where a D or F prefix limits an item to directories or files.
--chown=USER:GROUPSet owner and groupForces one user and group on every file; leaving either side empty skips mapping for it.
--numeric-idsKeep numeric user and group IDsSends uid and gid numbers instead of matching names on both ends; uid 0 and group 0 are never mapped by name.
-OSkip times on directoriesLong form --omit-dir-times; advisable when the receiving directories are shared over NFS.

Deciding what to transfer 10

Without -t (or -a) modification times are not kept, so the next run cannot skip unchanged files and updates all of them, as with -I.

CommandWhat it does
-cCompare by checksumLong form --checksum; files of equal size are checksummed on both sides, which costs a lot of disk reading.
--size-onlySize-only compareIgnores modification times, which helps after a mirroring tool that did not keep timestamps exactly.
-ITransfer files that look unchangedLong form --ignore-times; switches off the size and time quick check, so every file is updated.
-uSkip newer destination filesLong form --update; a receiver file with a later modification time than the source is left alone.
--modify-window=NUMAllow a timestamp toleranceShort form -@; a value of 1 suits FAT filesystems, which store times in 2-second steps.
--existingUpdate existing files onlyAlias of --ignore-non-existing; nothing new, directories included, is created on the receiver.
--ignore-existingSkip files already on the receiverOnly files missing on the receiver are sent; existing directories are still entered.
-WCopy whole filesLong form --whole-file; turns off the delta algorithm, already the default when both paths are local.
--max-size=SIZEMax file sizeSuffixes like K, M or G mean 1024 multiples, while two-letter forms ending in B, such as kb, mean 1000.
--min-size=SIZESkip files below a sizeTakes the same size suffixes as --max-size and keeps small junk files out of the transfer.

Deleting files 9

CommandWhat it does
--deleteDelete files missing from the sourceNeeds -r or -d and a whole directory as source, not dir/*; try the command with -n first.
--delete-beforeDelete before the transferFrees space first on a nearly full filesystem, but delays the start of copying.
--delDelete during the transferAlias of --delete-during, the mode --delete uses by default with rsync 3.0.0 or newer.
--delete-delayFind during, delete afterwardsDeletions are worked out while copying and carried out at the end; pairs well with --delay-updates.
--delete-afterDelete after the transferLets new per-directory merge files shape this run's deletions, at the cost of a full scan up front.
--delete-excludedAlso delete excluded filesExclude rules then act on the sender only, so matching receiver files lose their protection from deletion.
--max-delete=NUMCap the number of deletionsFurther deletions are skipped and rsync exits with code 25; a value of 0 only warns.
--ignore-errorsDelete despite I/O errorsNormally a sender I/O error switches deletion off to protect the destination.
--remove-source-filesRemove sent files from the sourceDirectories stay; use it only on files that nothing is still writing to.

Filtering files 12

Rules are checked in order and the first match decides, so an include placed after the exclude it should override has no effect.

CommandWhat it does
--exclude=PATTERNExclude matching filesShort for -f'- PATTERN'; the first matching rule wins, so put an --include before it.
--exclude-from=FILERead excludes from a fileOne pattern per line; blank lines and lines starting with ; or # are ignored.
--include=PATTERNRe-include matching filesShort for -f'+ PATTERN'; it only helps when placed ahead of the exclude it should limit.
--include-from=FILERead includes from a fileUses the same one-pattern-per-line format as --exclude-from.
--files-from=FILESend only listed filesImplies -R and -d but not -r; a FILE of - reads the list from standard input.
rsync -a --files-from=/tmp/foo /usr remote:/backupCopy a list of pathsEach listed path keeps its form under the destination: an entry bin becomes remote:/backup/bin.
-f RULEAdd a filter ruleLong form --filter; repeat it to build a rule list and quote rules containing spaces.
-FUse .rsync-filter filesReads per-directory .rsync-filter rules; a second -F also keeps those files out of the transfer.
-CSkip CVS-style filesLong form --cvs-exclude; skips a built-in list of version-control and build leftovers plus .cvsignore names.
-mPrune empty directoriesLong form --prune-empty-dirs; directories left empty by filter rules are not created on the receiver.
rsync -avm --del --include='*.pdf' -f 'hide,! */' src/ destCopy only PDF filesCreates only the directories that hold PDFs and removes everything else from the destination.
rsync -ai --del -f'- *.o' -f'- cmd' src host:/dest/Skip build output both waysThe excludes hide object files from the sender and protect the receiver's own copies from deletion.

Backups and snapshots 7

CommandWhat it does
-bKeep backups of replaced filesLong form --backup; overwritten or deleted files are renamed with a ~ suffix unless told otherwise.
--backup-dir=DIRBackup replacedImplies -b; a relative DIR sits inside the destination, so an absolute or ../ path is usually better.
--suffix=SUFFIXSet the backup suffixThe default is ~ without --backup-dir and an empty string when a backup directory is used.
--link-dest=DIRHard-link unchanged filesFiles matching DIR in every preserved attribute become hard links; a relative DIR is relative to the destination.
rsync -av --link-dest=$PWD/prior_dir host:src_dir/ new_dir/Snapshot against a prior copyWorks best into an empty new_dir; unchanged files are linked from prior_dir instead of being sent.
--compare-dest=DIRSkip files found in another treeFiles identical to those in DIR are not sent, leaving a sparse tree of just the changes.
--copy-dest=DIRCopy unchanged files locallyLike --compare-dest, but unchanged files are copied from DIR so the new tree is complete.

Interrupted and large transfers 12

CommandWhat it does
--partialKeep partial filesAn interrupted file is kept instead of deleted, so the next run can finish it much faster.
--partial-dir=DIRHold partial files apartImplies --partial; the partial file waits in DIR and is deleted once the next run has used it.
-PPartial plus progressSame as --partial --progress, intended for long transfers that might be cut off.
--appendAppend to growing filesSafe only when every file just grows and the receiver's existing data matches the sender's.
--append-verifyAppend with full checksumLike --append, but the existing data is part of the checksum check, slower yet safer.
--inplaceWrite into destination filesUpdates the file directly instead of building a temporary copy, so hard links to it stay intact.
--delay-updatesRename updated files at the endUpdated files wait in a .~tmp~ holding directory and move into place together, almost atomically.
-T DIRPut temporary files elsewhereLong form --temp-dir; by default each temporary file is created next to its destination file.
--timeout=SECONDSSet an I/O timeoutrsync exits when no data moves for that long; the default of 0 never times out.
--bwlimit=RATEBandwidth limitA plain number means units of 1024 bytes per second; suffixes such as m work and 0 means no limit.
--stop-after=MINSStop after some minutesAlso spelled --time-limit; only the local side is told unless -M passes it on.
--stop-at=y-m-dTh:mStop at a set timeTakes local time such as 2000-12-31T23:59; shortened forms mean the next moment that matches.

Remote shell and network 11

CommandWhat it does
-e COMMANDChoose the remote shellLong form --rsh; ssh is the usual default, and the command may include its own arguments.
-e 'ssh -p 2234'Connect on another ssh portThe whole shell command, options included, has to reach rsync as one quoted argument.
--rsync-path=PROGRAMSet the remote rsync programNeeded when rsync is not on the remote shell's path, for example /usr/local/bin/rsync.
rsync -avR --rsync-path="cd /a/b && rsync" host:c/d /e/Start remote rsync in a directoryPROGRAM runs through a shell, so a cd first moves the base that -R paths start from.
-zCompress during transferLong form --compress; helps on slow links, and rsync --version lists the methods your build has.
--compress-choice=STRPick a compression algorithmAlso --zc; choices include zstd, lz4, zlibx, zlib and none, and any choice except none turns on -z.
--compress-level=NUMSet the compression levelAlso --zl; implies -z unless the level means off for the algorithm in use, like 0 for zlib.
-M OPTIONPass an option to the remote sideLong form --remote-option; for settings such as --log-file that should apply on one side only.
-sSend arguments via the protocolLong form --secluded-args; names and most options bypass the remote shell's command line, and wildcards are expanded by rsync.
-4Prefer IPv4Applies to daemon sockets and is forwarded to ssh when rsync can tell ssh is the remote shell.
-6Prefer IPv6The IPv6 counterpart; other remote shells need their own hint passed inside the -e command.

Connecting to a daemon 8

CommandWhat it does
rsync somehost.mydomain.com::List a daemon's modulesNaming the host without a module prints the modules that daemon allows to be listed.
rsync -av host::src /destCopy a whole daemon moduleFetches every file of the module called src; protected modules prompt for a password.
rsync -av --rsh=ssh host::module /destReach a daemon module over sshDaemon features over a shell connection need --rsh on the command line; setting RSYNC_RSH does not enable them.
rsync -av -e "ssh -l ssh-user" rsync-user@host::module /destUse separate ssh and module usersWith -l handed to ssh, the user@ prefix only names the account for the module login.
--password-file=FILERead the daemon password from a fileA FILE of - means standard input; a world-readable file is refused, and ssh passwords are not covered.
--port=PORTUse another daemon portOnly needed with the double-colon syntax, since a URL can carry the port; the default is 873.
--contimeout=SECONDSLimit the daemon connect waitrsync gives up with an error when the daemon connection takes longer than this.
--no-motdHide the daemon's welcome messageAlso suppresses the module list of a host-only request, so leave it off when listing modules.

Running a daemon 4

CommandWhat it does
--daemonRun rsync as a daemonDetaches into the background unless standard input is a socket, in which case it assumes inetd.
--config=FILEUse another rsyncd.confOnly relevant with --daemon; the usual default is /etc/rsyncd.conf.
--no-detachKeep the daemon in the foregroundRequired for a Cygwin service and useful under supervisors such as daemontools.
rsync --daemon -M pidfile=/path/rsync.pidOverride a daemon setting-M (--dparam) sets a global rsyncd.conf parameter at startup, here the location of the pid file.

Notes

The core command

-a is archive mode, the same as -rlptgoD: recursion plus symlinks, permissions, times, group, owner (when the receiver runs as super-user) and device and special files. ACLs, extended attributes and hard links need -A, -X and -H on top. -v lists files and -z compresses file data in transit. A trailing slash on the source means "the contents of": rsync -avz foo:src/bar/ /data/tmp fills /data/tmp, while rsync -avz foo:src/bar /data/tmp creates /data/tmp/bar. A single colon after the host uses a remote shell, normally ssh, and -e 'ssh -p 2234' passes options such as a port to it. --progress shows per-file progress and --bwlimit=RATE caps throughput, in units of 1024 bytes per second when the number has no suffix.

Mirroring safely

--delete removes files in the destination that no longer exist in the source, turning a sync into a mirror. It only acts on directories sent whole (dir or dir/, not dir/*) and needs recursion. Run the same command with -n first, together with -v or -i, to see what would go; --max-delete=NUM caps the number of deletions, and 0 only warns. --backup-dir=DIR moves replaced or deleted files into a backup directory instead of discarding them. --exclude=PATTERN skips matching files (repeatable, or --exclude-from=FILE for a list), and excluded files are also kept safe from deletion unless --delete-excluded is given. --max-size=SIZE skips large files.

Speed and partials

--partial keeps a partially transferred file so the next run finishes it faster, and -P combines it with --progress. --size-only compares by size alone, which helps after a mirroring tool that did not keep timestamps, but it cannot see an edit that leaves the size unchanged. For FAT filesystems, which store times in 2-second steps, the manual suggests --modify-window=NUM with a value of 1 instead. rsync -av --list-only foo* dest/ lists files instead of copying them, which is a quick way to confirm a path before syncing to it.

Questions

Does a trailing slash on the source directory change what rsync copies?

Yes. rsync -avz foo:src/bar /data/tmp creates /data/tmp/bar, while rsync -avz foo:src/bar/ /data/tmp copies only what is inside bar. The attributes of bar are applied in both cases. A bare host or module reference such as rsync -av host: /dest needs no slash to copy contents.

How can I see what --delete would remove before running it?

Add -n (dry run) with -v or -i to the same command: nothing is changed and the itemized output matches what a real run would do. --max-delete=NUM with 0 warns about extraneous files without deleting any.

Why does rsync update every file again on each run?

The quick check compares size and modification time. Without -t (or -a) times are not preserved, so the next run behaves as if -I had been given. On FAT filesystems --modify-window=NUM with 1 absorbs their 2-second time resolution.

How do I resume a large transfer that was interrupted?

Run it with --partial, or -P to add progress output, so a half-copied file is kept and finished on the next run. --partial-dir=DIR keeps such files out of the destination until they are complete. --append-verify suits only files that grow and never change in place.

How do I connect to an ssh server on a non-standard port?

Pass the whole ssh command as one argument: -e 'ssh -p 2234'. Settings in .ssh/config work as well, since rsync starts ssh as its remote shell.

Sources and checks

Every row on this page was matched to a line in the documentation above on . A binding that could not be found there is not listed.

Found a wrong or missing key? Tell us and it gets checked against the source. How we verify describes the process and its limits.