robocopy

On this page 7

robocopy (Robust File Copy) is the built-in Windows command-line utility for copying and synchronizing files and directory trees reliably, including across unstable network links. In PowerShell & command line work on Windows, it is the standard tool for bulk data migration, scheduled replication and server-to-server transfers, because it copies only what has changed, retries failed operations and preserves security information and timestamps.

Unlike the older copy and xcopy commands, robocopy treats a copy job as a comparison between a source and a destination. It decides file by file whether to copy, skip or delete, which makes repeated runs fast and predictable. It runs equally well from Command Prompt, a batch file or a PowerShell script.

How robocopy decides what to copy

robocopy copies a file only when the source and destination versions differ, which is why it is described as an incremental copy tool. By default it compares file size and last-write timestamp; when both match, the file is classified as “same” and skipped. Files that exist only in the source are “new”, files that differ are “newer” or “older”, and files that exist only in the destination are “extra”.

This classification drives everything else. A plain run copies new and changed files, while the mirror option also deletes extra files so that the destination becomes an exact replica. The basic syntax is robocopy <source> <destination> [files] [options], and when no file filter is given, the pattern *.* is assumed.

The following table shows how robocopy classifies files during a comparison and what it does with each class by default.

ClassConditionDefault action
New fileExists only in the sourceCopied
Newer or changedSize or timestamp differsCopied, overwriting the target
SameSize and timestamp matchSkipped
Extra fileExists only in the destinationListed; deleted only with /PURGE or /MIR
MismatchedFile in one tree, folder of same name in the otherReported, not resolved
File classes in a robocopy comparison

Because the comparison relies on metadata rather than content hashes, robocopy is fast but not a verification tool. Timestamp precision differences between file systems, such as FAT32 with its two-second resolution, can cause unnecessary recopying unless the /FFT option is used.

Key options and parameters

robocopy has more than eighty switches, but a small set covers most administrative work. The most consequential choices concern recursion, deletion, attribute copying and failure handling, and they should be decided deliberately for every job.

SwitchEffectPractical note
/ECopies subdirectories, including empty onesSafe default for full trees
/MIRMirrors the tree: /E plus /PURGEDeletes destination extras
/COPY:DATSOUSelects data, attributes, timestamps, security, owner, auditingDefault is /COPY:DAT
/DCOPY:DATCopies directory attributes and timestampsKeeps folder dates intact
/Z and /BRestartable mode and backup mode/ZB falls back to backup mode
/MT:nMultithreaded copying with n threadsDefault 8, range 1 to 128
/R:n and /W:nRetry count and wait secondsDefaults are 1,000,000 and 30
/LLists actions without copyingUse for a dry run
/LOG:fileWrites output to a log filePair with /TEE and /NP
Frequently used robocopy switches

The retry defaults are a common trap. One million retries with a 30-second wait means that a single locked file can stall a job for weeks, so production scripts almost always set values such as /R:2 /W:5. Backup mode (/B) uses the Backup Operators privilege to read files regardless of their access control lists, and it requires an elevated session.

Multithreading with /MT greatly improves throughput for many small files over a network, typically between 8 and 32 threads. It is incompatible with the /IPG bandwidth throttle, and very high values can saturate storage or the network instead of speeding the job up.

Exit codes and automation

robocopy reports its result through a bitmask exit code rather than the usual zero-for-success convention. This matters in automation, because a scheduler or CI pipeline that treats any nonzero code as failure will flag successful copies as errors.

ValueMeaningTreat as
0No files copied, trees already in syncSuccess
1One or more files copiedSuccess
2Extra files or folders detectedSuccess, informational
4Mismatched files or folders detectedWarning, review needed
8Some files or folders could not be copiedFailure
16Fatal error, no files copiedFailure
robocopy exit code bits

The values combine, so 3 means files were copied and extras were found. The practical rule is that codes below 8 indicate success. In a batch file the check is if %ERRORLEVEL% GEQ 8, and in PowerShell the result is read from $LASTEXITCODE, which also lets a script translate the code into an exception for monitoring systems.

For scheduled jobs, administrators usually combine robocopy with Task Scheduler, a log file per run and the /NP switch to suppress percentage counters that bloat logs. The /MON:n and /MOT:m options can keep robocopy running and recopy when changes occur, but a scheduled task is easier to monitor.

How robocopy compares with other copy tools

robocopy sits between simple copy commands and full replication services. Choosing the right tool depends on whether the task is a one-time transfer, a repeated synchronization or continuous replication, and on whether security metadata must survive the move.

ToolBest forMain limitation
copy and xcopyQuick ad hoc copiesNo mirroring, weak retry handling, deprecated xcopy
Copy-Item cmdletSimple copies inside PowerShell scriptsNo incremental logic or restartable mode
robocopyMigrations, mirrors, scheduled replicationMetadata comparison only, no open-file copy
DFS ReplicationContinuous multi-site folder replicationRequires Active Directory and careful design
Storage Migration ServiceWhole file server migrationsHeavier setup through Windows Admin Center
robocopy and related Windows copy mechanisms

A frequent pattern combines both worlds: a PowerShell script builds the list of shares and logs, while robocopy performs the actual transfer. Wrapping robocopy this way keeps its speed and resilience while adding error handling and reporting.

Limitations and common mistakes

The most destructive mistake is a reversed or wrong path with /MIR. Because mirroring deletes everything in the destination that is absent from the source, pointing /MIR at an empty or incorrect source can erase a full data set within minutes. A dry run with /L before every new mirror job is the standard safeguard.

  • Open files are not copied: robocopy does not use Volume Shadow Copy Service, so databases and locked files need a snapshot or a maintenance window.
  • Permissions are not copied by default: without /COPY:DATSOU or /SEC, migrated data inherits destination permissions.
  • Trailing backslashes break quoting: a path such as "D:\Data\" escapes the closing quote, so paths should end without a backslash.
  • Long paths are supported, but other tools and applications may still fail on paths beyond 260 characters after the copy.
  • Junction loops can cause endless recursion; the /XJ option excludes junction points.

Finally, robocopy is not a backup solution by itself. A mirror faithfully replicates accidental deletions and ransomware encryption, so it complements versioned backups rather than replacing them.

A non-technical view

robocopy is a careful moving crew for files. Instead of carrying every box again each time, it walks through both rooms, notes what is already in place and moves only what is new or changed. If a door is stuck, it waits a moment and tries again rather than giving up on the whole move.

Its strongest feature is also its risk. In mirror mode it makes the second room look exactly like the first, which includes throwing out anything the first room does not have. Used carefully, it makes large copies fast and dependable; used carelessly, it can delete data just as efficiently.

A concrete example

An IT administrator at a mid-sized engineering firm must move 4 TB of project files, about 3 million small files, from an aging file server to a new Windows Server 2022 machine with minimal downtime. Copying everything in one weekend is not realistic, so the administrator plans a staged migration with robocopy.

During the week, a seeding job runs from an elevated prompt with /MIR /COPY:DATSOU /DCOPY:DAT /B /MT:32 /R:2 /W:5 /NP /LOG:seed.log, after a dry run with /L confirmed the paths. The first pass takes about two days. Each evening, the same command runs again and copies only the changed files, finishing in under an hour.

On Friday evening the old shares are set to read-only and a final delta pass completes in about 25 minutes with exit code 1. The administrator checks the log for code 8 entries, repoints the drive mappings and opens the new server on Monday morning. Users keep their permissions and folder dates, and the cutover window shrinks from a weekend to under one hour.