robocopy — Robust File Copy

What it is

robocopy (Robust File Copy) is a powerful Windows command-line tool for copying and synchronising directory trees, shipping with all Windows versions since Vista as C:\Windows\System32\robocopy.exe. It supports multi-threaded copying, automatic retry on failure, mirror mode, granular exclusion lists, ACL and timestamp preservation, and structured log files. Reach for robocopy over xcopy whenever you need reliability on network paths, incremental sync, or fine-grained control over what gets copied; for simple single-file copies, copy is sufficient.

Availability

robocopy ships with Windows Vista and later as C:\Windows\System32\robocopy.exe. On older systems it was available in the Windows Server Resource Kit. No installation is needed on modern Windows.

robocopy /?

Output:

-------------------------------------------------------------------------------
   ROBOCOPY     ::     Robust File Copy for Windows
-------------------------------------------------------------------------------

  Started : ...
              Usage :: ROBOCOPY source destination [file [file]...] [options]

Syntax

Unlike copy and xcopy, source and destination are directories, not files. File patterns are listed after the destination; if omitted, all files (*.*) are copied. Switches are grouped by function below.

robocopy SOURCE DESTINATION [file...] [options]

Output: (structured log output; see below)

Essential options

Basic recursive copy

The minimal recursive copy: source and destination directories, /E to include empty subdirectories, /R:3 /W:5 to limit retry noise.

robocopy C:\Projects\myapp D:\Backup\myapp /E /R:3 /W:5

Output:

-------------------------------------------------------------------------------
   ROBOCOPY     ::     Robust File Copy for Windows
-------------------------------------------------------------------------------

  Started : Monday, 28 April 2026 10:00:00
   Source : C:\Projects\myapp\
     Dest : D:\Backup\myapp\

    Files : *.*

  Options : *.* /E /R:3 /W:5 /DCOPY:DA /COPY:DAT /NP /RTH

------------------------------------------------------------------------------

	                   3	C:\Projects\myapp\
100%	                   	main.py
100%	                   	utils.py

------------------------------------------------------------------------------

               Total    Copied   Skipped  Mismatch    FAILED    Extras
    Dirs :         2         2         0         0         0         0
   Files :         2         2         0         0         0         0
   Bytes :   12.5 k    12.5 k         0         0         0         0
   Times :   0:00:01   0:00:00                       0:00:00   0:00:00
   Ended : Monday, 28 April 2026 10:00:01

Mirror mode

/MIR is a true mirror: it copies new/changed files from source to destination AND deletes any files at the destination that no longer exist in the source. Use with care — deletions are permanent.

robocopy C:\Website D:\Deploy\Website /MIR /R:3 /W:5

Output:

    Dirs :         5         3         2         0         0         1
   Files :        20        15         3         0         0         2

The Extras column shows files deleted from destination.

Multi-threaded copy

/MT enables parallel file transfers — significant speedup on fast networks or SSDs with many small files. Default is 8 threads; increase to 32 or 64 for network shares.

robocopy C:\LargeDataset D:\Mirror\LargeDataset /E /MT:32 /R:3 /W:5 /NP

Output:

   Files :      5000      5000         0         0         0         0
   Bytes :   25.6 g    25.6 g         0         0         0         0
   Times :   0:02:14   0:02:11

Incremental sync

Robocopy skips files where the source and destination have the same size and timestamp — making it naturally incremental. /XO explicitly excludes older destination files, ensuring only newer source files overwrite.

rem Sync: copy only files newer than destination copy
robocopy C:\Source D:\Dest /E /XO /R:3 /W:5

Output:

   Files :       100        12        88         0         0         0

Exclusions

/XF excludes files matching patterns; /XD excludes directories. Multiple patterns can be listed space-separated or with repeated flags.

robocopy C:\Projects\myapp D:\Deploy\myapp /E /R:3 /W:5 ^
  /XD .git __pycache__ node_modules .venv ^
  /XF *.pyc *.log .env

Output:

   Files :        30        28         0         0         0         0

rem Exclude hidden and system files
robocopy C:\Source D:\Dest /E /XA:HS /R:3 /W:5

Output:

   Files :        50        47         0         0         0         0

Date and size filtering

/MAXAGE and /MINAGE filter by last-modified date (in days or YYYYMMDD). /MAXSIZE and /MINSIZE filter by byte count.

rem Copy only files modified in the last 7 days
robocopy C:\Logs D:\RecentLogs /S /MAXAGE:7 /R:3 /W:5

Output:

   Files :       200        14       186         0         0         0

rem Copy only files modified on or after 1 April 2026
robocopy C:\Data D:\Snapshot /E /MAXAGE:20260401 /R:3 /W:5

Output:

   Files :       500        42       458         0         0         0

Logging

/LOG: writes the full job summary to a file (overwrites). /LOG+: appends. /TEE writes to both log and screen. Combine with /NFL /NDL /NJH /NJS to slim down verbose output.

rem Silent run with log file only
robocopy C:\Source D:\Dest /E /R:3 /W:5 /NP /NFL /NDL /LOG:C:\Logs\robocopy.log

Output: (no screen output — written to log file)

rem Tee: log file AND screen, summary only
robocopy C:\Source D:\Dest /E /R:3 /W:5 /NP /NFL /NDL /NJH /TEE /LOG+:C:\Logs\robocopy.log

Output:

               Total    Copied   Skipped  Mismatch    FAILED    Extras
    Dirs :         5         2         3         0         0         0
   Files :        30        10        20         0         0         0

Exit codes

Robocopy uses a bitmask exit code: values ≤ 7 are non-error. Check %ERRORLEVEL% in scripts to distinguish success from failure.

robocopy C:\Source D:\Dest /E /R:3 /W:5
if %ERRORLEVEL% GEQ 8 (
    echo ERROR: Robocopy failed with code %ERRORLEVEL%
    exit /b 1
)
echo Success.

Output:

Success.

Common pitfalls

1. /R default is 1,000,000 retries — always set /R:3 /W:5 or similar in scripts, or a single failed file locks the job indefinitely on network paths.
2. /MIR deletes destination extras — mirror mode is destructive; test with /L (dry run) before committing.
3. Exit codes ≤ 7 are not errors — if %ERRORLEVEL% NEQ 0 exit /b 1 will falsely fail on a code 1 (files copied ok). Use GEQ 8 instead.
4. /MT and /LOG together may interleave output — robocopy's multi-threaded output can scramble log lines; prefer /NFL /NDL with /MT for readable logs.
5. ACL copy requires backup privilege — /COPY:S (security/ACL) or /COPYALL silently skips ACLs without elevation; run as administrator for full fidelity copies.
6. Source path trailing backslash matters for some flags — robocopy normalises this, but if you see unexpected "extra" files deleted, check whether trailing \ is adding a level.

Real-world recipes

Nightly mirror backup with log rotation

@echo off
set SRC=C:\Users\alicedev\Documents
set DST=\\myhost\Backups\Documents
set LOG=C:\Logs\backup_%DATE:~-4,4%%DATE:~-10,2%%DATE:~-7,2%.log
robocopy %SRC% %DST% /MIR /R:5 /W:10 /MT:16 /NP /NFL /NDL /LOG:%LOG%
if %ERRORLEVEL% GEQ 8 echo BACKUP FAILED >> %LOG%

Output: (log written to dated file; no screen output)

Deploy a website, excluding dev artefacts

robocopy C:\Sites\mysite D:\Deploy\mysite /MIR /R:3 /W:5 /MT:8 ^
  /XD .git node_modules __pycache__ ^
  /XF .env *.log *.pyc ^
  /NP /TEE /LOG+:C:\Logs\deploy.log

Output:

   Files :       120       118         0         0         0         2

Copy large files with restart support over a slow VPN

robocopy C:\Data \\myhost\share\Data /E /Z /R:10 /W:30 /MT:4 /NP

Output:

   Bytes :    4.2 g     4.2 g         0         0         0         0
   Times :   0:15:42   0:15:39

Dry run before a mirror operation

robocopy C:\Source D:\Dest /MIR /L /NP /TEE

Output:

        *EXTRA File         D:\Dest\old_file.txt
               New File     C:\Source\new_feature.py

Network compression (/COMPRESS)

/COMPRESS requests SMB Compression on the wire when both endpoints support it (Windows 11 / Windows Server 2022 and later, with SMB 3.1.1). Robocopy negotiates the algorithm with the SMB redirector; if either peer can't compress, the transfer proceeds uncompressed without an error. Effective on slow links and on large, already-compressible content like text logs, source trees, or uncompressed images — but counter-productive for already-compressed data (zip, jpg, mp4) where it wastes CPU.

robocopy C:\Reports \\fileserver01\Backup\Reports /E /COMPRESS /R:3 /W:5 /MT:8

Output:

   Files :       512       512         0         0         0         0
   Bytes :  1.20 g    1.20 g         0         0         0         0
   Times :   0:00:42   0:00:40

Combine with /MT for the standard "ship a tree over WAN" pattern; the throughput gain depends on the link's bandwidth-delay product and the source data's compressibility.

Sparse-file handling (/SPARSE:Y|N)

/SPARSE:Y (the default) preserves the sparse state of NTFS files during copy — the destination ends up with the same allocated extents and "logical holes" as the source. This matters for VHD/VHDX images, database files, and any application that intentionally leaves unallocated ranges to save space. /SPARSE:N forces robocopy to fill the holes with zeros, producing a fully-allocated destination file that is bytewise identical but occupies disk space equal to its full logical size.

rem Default — preserve sparse extents (saves space on destination)
robocopy C:\VMs D:\Backup\VMs *.vhdx /E /R:3 /W:5

rem Force fully-allocated destination (compatibility with tools that don't understand sparse)
robocopy C:\VMs D:\Backup\VMs *.vhdx /E /SPARSE:N /R:3 /W:5

Output:

   Files :         3         3         0         0         0         0
   Bytes : 120.0 g   120.0 g         0         0         0         0

Use /SPARSE:N when copying to a destination that can't handle sparse files (FAT32, exFAT, third-party network filesystems) or when piping to a backup target that expects fully-allocated streams.

Block cloning opt-out (/NOCLONE)

When both source and destination live on the same ReFS volume — or on an NTFS volume on Windows Server 2025 / Windows 11 with the new copy-offload pipeline — robocopy uses block cloning to make a copy without physically duplicating data. The destination file is a fresh entry whose extents reference the same underlying blocks until either copy is modified (copy-on-write). This is dramatically faster than a real byte-for-byte copy and reduces wear on SSDs. /NOCLONE disables this optimisation and forces a full data copy — useful when you want the destination to land on different physical blocks (for diversity/durability testing) or when you're benchmarking raw throughput.

rem Default — fast clone when on the same ReFS volume
robocopy D:\VMs E:\Snapshots\VMs /E /R:0

rem Force a real data copy even when cloning is possible
robocopy D:\VMs E:\Snapshots\VMs /E /NOCLONE /R:0

Output:

   Files :        20        20         0         0         0         0
   Bytes : 240.0 g   240.0 g         0         0         0         0

/NOOFFLOAD is the related switch for Windows Copy Offload (the SMB-level "tell the storage array to do the copy" protocol used with SAN/NAS targets). Disable both with /NOOFFLOAD /NOCLONE if you specifically want bytes to traverse the network.

I/O throttling (/IoMaxSize, /IoRate, /Threshold)

Windows 11 and Windows Server 2022+ add a throttling group that caps robocopy's I/O footprint to avoid starving other processes on a shared host. The settings accept a byte count with optional k, m, or g suffix. The system enforces a 524 288-byte minimum regardless of what you request.

rem Cap robocopy at 5 MB/s for files over 10 MB — leave small files un-throttled
robocopy C:\Data D:\Backup\Data /E /IoRate:5m /Threshold:10m /R:3 /W:5

Output:

   Files :       423       423         0         0         0         0
   Bytes :  4.20 g    4.20 g         0         0         0         0
   Times :   0:14:00   0:13:58

Use the throttling group instead of /IPG (inter-packet gap) on modern Windows — /IPG is still supported but predates the I/O scheduler and is less precise.

Low free space mode (/LFSM)

/LFSM ("low free space mode") makes robocopy pause whenever the destination volume's free space drops below a floor, resuming once space comes back (typically as a deduplication or housekeeping job kicks in). /LFSM:<n>[kmg] sets the floor explicitly; bare /LFSM defaults to 10% of the destination volume. Incompatible with /MT and /EFSRAW.

rem Pause if the destination drops below 50 GB free, resume when space returns
robocopy C:\BigData D:\Archive\BigData /E /LFSM:50g /R:3 /W:5

Output:

   Bytes : 1.50 t    1.50 t         0         0         0         0
   Times :   2:14:08   1:55:23
   (paused 18m 45s waiting for free space)

This is the right tool for filling slow-replicating tiered storage where the destination's available capacity oscillates.

Junction and symlink handling (/SJ, /SL, /XJ, /XJD, /XJF)

By default robocopy follows directory junctions and copies their targets into the destination, which can balloon a backup or produce loops. The newer /SJ and /SL switches make robocopy copy the junction or symlink itself instead of the target — preserving the source's link topology. The legacy /XJ family excludes them entirely.

rem Preserve link topology — junctions stay as junctions
robocopy C:\Workspace D:\Mirror\Workspace /E /SJ /SL /R:3 /W:5

Output:

   Files :       400       400         0         0         0         0
   Junctions :    12        12         0         0         0         0

For deep dives where junctions form loops (common in Windows Update WinSxS hardlink farms), pair /XJ with an exclusion list (/XD .git node_modules) to keep the scope manageable.

Sources

Microsoft Learn — Robocopy (updated 2026-02-16) — confirmed parameters including /compress, /sparse, /noclone, /sj, /sl, /IoMaxSize, /IoRate, /threshold, /LFSM, /nooffload, /dcopy:E.