Build robocopy copy, mirror and move commands with the right switches.
robocopy (Robust File Copy) is the heavy-duty file copier built into every version of Windows since Vista and Server 2008. Unlike drag-and-drop, copy or xcopy, it retries on failure, preserves timestamps and NTFS permissions, copies with multiple threads, skips files that have not changed, and can mirror an entire directory tree. It is the standard tool for backups, server migrations and large folder syncs. This builder assembles the command with the right switches, warns before the destructive ones, and flags switch combinations that Microsoft documents as incompatible.
/L is a list-only preview. Robocopy walks the source and destination, works out exactly what it would copy, move or delete, and reports it without touching a single file. It is a modifier, not a mode: you add it to the command you are actually going to run, so the preview reflects the real thing. Add /L, read the log, remove /L, run it again. On any command containing /MIR or /PURGE this is the difference between a routine sync and an outage.
Robocopy separates what to do from how deep to go, and mixing them up is a common source of surprise.
| Switch | What it does |
|---|---|
/S | Include subdirectories, but skip empty ones |
/E | Include subdirectories, keeping empty ones |
/LEV:n | Only descend n levels into the tree |
/PURGE | Delete destination files and folders that no longer exist in the source |
/MIR | Mirror a tree. Exactly equivalent to /E plus /PURGE |
/MOV | Move files: delete each source file after it copies successfully. Directories stay |
/MOVE | Move files and directories: the source tree is removed |
/MIR is the switch that loses data. Because it implies /PURGE, anything in the destination that is not in the source is deleted, including files that were only ever meant to live at the destination. If the source path is wrong, empty or unmounted, robocopy concludes that every destination file is extraneous and removes it. Preview with /L first, every time.
By default robocopy copies /COPY:DAT — data, attributes and timestamps. Security descriptors are not included, so a plain copy lands with permissions inherited from the destination folder rather than the ones the files had.
| Flag | Meaning |
|---|---|
D | File data |
A | Attributes |
T | Timestamps |
S | NTFS access control lists |
O | Owner information |
U | Auditing information |
X | Skip alternate data streams (ignored when /B or /ZB is used) |
/SEC is shorthand for /COPY:DATS and /COPYALL for /COPY:DATSOU. A widely missed detail: /COPYALL does not include /DCOPY:E, so extended attributes on directories are still skipped unless you set the directory copy flags yourself. Directories default to /DCOPY:DA.
Copying ACLs, owner or audit data requires elevation. Run the shell as Administrator, and consider backup mode below if permissions on the source would otherwise block the read.
/Z copies in restartable mode, so an interrupted large file resumes rather than starting over — useful across an unreliable WAN, at some cost to throughput. /B copies in backup mode, which uses the Backup and Restore Files privileges to read files the running account has no permission to open. /ZB is the pragmatic combination: try restartable, fall back to backup mode on access denied. Backup mode requires membership of Administrators or Backup Operators, in an elevated session.
/MT[:n] copies with n threads, default 8, maximum 128. On a folder of many small files this is the single largest speed win available. Two constraints are worth remembering: /MT cannot be combined with /IPG or /EFSRAW, and Microsoft recommends redirecting output to a log with /LOG when multithreading, because console writes from many threads become the bottleneck. /J enables unbuffered I/O, which helps noticeably on very large files such as VHDX or database backups.
Newer builds add throttling for copies that must not saturate a production server: /IoMaxSize caps the size of each read/write cycle, /IoRate caps bytes per second, and /Threshold sets the file size below which throttling is not applied. All three accept K, M and G suffixes. Windows Server 2022 and later also support /COMPRESS, which requests SMB compression during transfer — a real gain on a slow link with compressible data, and a waste of CPU on already-compressed media.
Robocopy's built-in defaults are /R:1000000 and /W:30 — one million retries, thirty seconds apart. A single locked or unreadable file will therefore stall the job for roughly a year. Every production robocopy command should set these explicitly; /R:3 /W:5 is a sensible starting point, and /R:0 suits a first pass where you intend to catch stragglers on a second run.
/LOG:file overwrites a log, /LOG+:file appends, and /TEE mirrors output to the console as well. Always pair logging with /NP: without it, robocopy writes every percentage update into the file, and a large job produces a log full of carriage-return spam that is effectively unreadable. For a compact log that still tells you what happened, combine /NP /NFL /NDL /NJH and keep the job summary.
/SAVE:name writes the current parameters to a job file (robocopy appends the .RCJ extension itself), and /JOB:name reads them back. Pair /SAVE with /QUIT to write the job without running the copy, then schedule robocopy /JOB:name in Task Scheduler. Switches given on the command line override those in the job file, and /NOSD and /NODD let a job omit the source or destination so it can be supplied at run time.
Robocopy does not follow the usual convention that zero means success and anything else is failure. Its exit code is a bitmask, and any value below 8 indicates success.
| Code | Meaning |
|---|---|
| 0 | No files copied; source and destination already matched |
| 1 | Files copied successfully |
| 2 | Extra files or directories present at the destination |
| 4 | Mismatched files or directories |
| 8 | Some files or directories could not be copied |
| 16 | Fatal error; nothing was copied |
In a batch file, test with if %ERRORLEVEL% GEQ 8. Testing NEQ 0 is the classic mistake: it reports a routine successful copy as a failed job, which is why so many scheduled robocopy tasks show up red in monitoring for no reason.
They solve the same problem on different platforms. Robocopy is the Windows answer and is far better integrated with NTFS permissions, alternate data streams and Task Scheduler. rsync is the Unix equivalent and wins over slow links, because its delta-transfer algorithm sends only the changed portions of files rather than whole files. Copying between Windows servers, use robocopy; between Linux hosts or across a constrained WAN, use rsync.
robocopy is the modern, robust replacement for xcopy. It adds multithreaded copying, automatic retries on locked files, mirroring, restartable transfers, detailed logging, and preservation of NTFS permissions. xcopy is older and lacks these features, which is why robocopy is preferred for backups and migrations.
The /MIR switch mirrors a directory tree, making the destination an exact copy of the source. It copies new and changed files and, critically, deletes anything in the destination that is not in the source. Always preview it with /L first, because pointing it at the wrong folder can erase data.
By default robocopy retries a failed or locked file one million times, waiting 30 seconds between each attempt, which can stall for days. Add /R:3 /W:5 to retry only three times with a five-second wait so it moves on quickly instead of hanging.
robocopy uses bitmapped exit codes. Values 0 through 7 indicate success: 0 means nothing changed, 1 means files were copied, and higher values in that range mean extras or mismatches were handled. An exit code of 8 or above signals a genuine failure, so scripts should only treat 8+ as an error.