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.
| Class | Condition | Default action |
|---|---|---|
| New file | Exists only in the source | Copied |
| Newer or changed | Size or timestamp differs | Copied, overwriting the target |
| Same | Size and timestamp match | Skipped |
| Extra file | Exists only in the destination | Listed; deleted only with /PURGE or /MIR |
| Mismatched | File in one tree, folder of same name in the other | Reported, not resolved |
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.
| Switch | Effect | Practical note |
|---|---|---|
| /E | Copies subdirectories, including empty ones | Safe default for full trees |
| /MIR | Mirrors the tree: /E plus /PURGE | Deletes destination extras |
| /COPY:DATSOU | Selects data, attributes, timestamps, security, owner, auditing | Default is /COPY:DAT |
| /DCOPY:DAT | Copies directory attributes and timestamps | Keeps folder dates intact |
| /Z and /B | Restartable mode and backup mode | /ZB falls back to backup mode |
| /MT:n | Multithreaded copying with n threads | Default 8, range 1 to 128 |
| /R:n and /W:n | Retry count and wait seconds | Defaults are 1,000,000 and 30 |
| /L | Lists actions without copying | Use for a dry run |
| /LOG:file | Writes output to a log file | Pair with /TEE and /NP |
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.
| Value | Meaning | Treat as |
|---|---|---|
| 0 | No files copied, trees already in sync | Success |
| 1 | One or more files copied | Success |
| 2 | Extra files or folders detected | Success, informational |
| 4 | Mismatched files or folders detected | Warning, review needed |
| 8 | Some files or folders could not be copied | Failure |
| 16 | Fatal error, no files copied | Failure |
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.
| Tool | Best for | Main limitation |
|---|---|---|
| copy and xcopy | Quick ad hoc copies | No mirroring, weak retry handling, deprecated xcopy |
| Copy-Item cmdlet | Simple copies inside PowerShell scripts | No incremental logic or restartable mode |
| robocopy | Migrations, mirrors, scheduled replication | Metadata comparison only, no open-file copy |
| DFS Replication | Continuous multi-site folder replication | Requires Active Directory and careful design |
| Storage Migration Service | Whole file server migrations | Heavier setup through Windows Admin Center |
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:DATSOUor/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
/XJoption 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.