View source for Robocopy

{{Short description|Windows command-line component specialized in file transfer}}
{{Infobox software
| name                   = Robocopy
| other_names            = Robust File Copy for Windows
| logo                   = 
| screenshot             = 
| caption                = 
| developer              = [[Microsoft]]
| operating_system       = [[Windows NT 4]] and later
| included with          = [[Windows Vista]] and later
| released               = {{Release year|df=yes|1996}}
| genre                  = [[Command (computing)|Command]]
| latest release version = {{Latest stable software release/Windows 11}}
| license                = [[Freeware]]
| website                = {{URL|https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy}}
}}
'''Robocopy''' is a [[command line interface|command-line]] [[file transfer]] [[utility]] for [[Microsoft Windows]].  Robocopy is functionally more comprehensive than [[copy (command)|the COPY command]] and [[XCOPY]], but replaces neither. Created by Kevin Allen<ref>{{cite web |title=AMA with Dave Plummer, creator of Task Manager |url=https://www.reddit.com/r/IAmA/comments/kfpjhg/i_am_dave_plummer_author_of_windows_task_manager/ggdh12l?context=3 |website=Reddit.com |date = 18 December 2020|access-date=19 December 2020}}</ref> and first released as part of the [[Windows NT 4.0]] [[Windows Resource Kit|Resource Kit]], it has been a standard feature of Windows since [[Windows Vista]] and [[Windows Server 2008]].

==Features==
Robocopy provides features not found in the built-in Windows [[copy (command)|COPY]] and [[XCOPY]] commands, including the following:

* Recovering from temporary loss of network connectivity (Incomplete files are marked with a date stamp of 1970-01-01 and contain a recovery record so Robocopy knows where to continue from).
* Detecting and skipping [[NTFS junction point]]s, which, under certain circumstances, may cause copying failures because of infinite loops (with the <code>/XJ</code> switch).
* Preserving any combination of the following: file contents, attributes, metadata (e.g., original timestamps), NTFS [[Access Control List|ACL]]s (DACLs, SACLs, and owner). For example, it is possible to copy ACLs from one file to another. Before version XP026, however, this capability was limited to files only, not folders.
* Utilizing the [[Windows NT]] "Backup Files and Directories" privilege (<code>SeBackupPrivilege</code>, normally not available to standard user accounts) to bypass NTFS ACLs that would otherwise impede transfer (requires the <code>/B</code> switch).<ref>{{cite web | url = http://theether.net/download/Microsoft/Utilities/robocopy.pdf | title = Robocopy.exe - Robust File Copy Utility - Version XP010 | publisher = [[Microsoft]] | year = 2003 | quote = Backup mode copies [...] enable you to copy some files as a Backup Operator that you would not be able to copy as a normal user. }}
</ref><ref>{{cite web | url = http://technet.microsoft.com/en-us/library/cc756898(v=ws.10).aspx | title = Default groups | date = 6 June 2011 | publisher = Microsoft | quote = Backup Operators [...] Members of this group can back up and restore all files [...], regardless of their own individual permissions on those files. }}</ref>
* Persistence by default, with a programmable number of automatic retries if a file cannot be copied.
* The mirror mode, which keeps two directory trees synchronized by also deleting files in the destination that are not present in the source.
* Skipping files already in the destination folder with identical size and timestamp.
* Progress indicator
* Support for paths exceeding 259 characters, up to a theoretical limit of about 32,000 characters.<ref>{{cite web|url=http://www.windowsitpro.com/content1/topic/robocopy-xp010-faq/catpath/migration/page/2|title=Robocopy XP010 FAQ|last=Lewis|first=Dick|date=15 November 2004|website=Windows IT Pro|publisher=Penton Media|page=2|archive-url=https://web.archive.org/web/20121009110523/http://www.windowsitpro.com/content1/topic/robocopy-xp010-faq/catpath/migration/page/2|archive-date=9 October 2012|url-status=dead}}</ref>
* Multithreaded copying (introduced with [[Windows 7]] and [[Windows Server 2008 R2]]).<ref>{{cite web |last1=Holliday |first1=Grant |title=Multi-threaded robocopy for faster copies |url=https://blogs.msdn.microsoft.com/granth/2009/12/07/multi-threaded-robocopy-for-faster-copies/ |website=Grant Holliday's Blog |publisher=[[Microsoft]] |archive-url=https://web.archive.org/web/20180813013804/https://blogs.msdn.microsoft.com/granth/2009/12/07/multi-threaded-robocopy-for-faster-copies/ |archive-date=13 August 2018 |date=7 December 2009 |url-status=dead}}</ref>
* Return codes (used in automation).<ref>{{cite web|url=https://learn.microsoft.com/en-US/troubleshoot/windows-server/backup-and-storage/return-codes-used-robocopy-utility |title=Return codes that are used by the Robocopy utility in Windows Server 2008 or Windows Server 2008 R2 |website=Windows Server troubleshooting |via=[[Microsoft Learn]] |publisher=[[Microsoft]] |date=23 February 2023 |first1=Han |last1=Liang |first2=Lucy |last2=Zou |first3=Simonx |last3=Xu}}</ref>

===Compression===
Since [[Windows Server 2019]] and [[Windows 10]], Robocopy supports [[Server Message Block|SMB]] compression for transferring files across a network. If the <code>/compress</code> is specified, the destination computer supports SMB compression, and the files being copied are compressible, the operation enjoys significant performance improvements. The SMB compression adds inline whitespace compression to file transfers. Compression is also available with the <code>[[XCOPY]]</code> command and [[Hyper-V]] [[live migration]] with SMB.<ref>{{Cite web |title=RoboCopy supports Copying Files over SMB with Compression on Windows Server 2019, and beyond |first=Sander |last=Berkouwer |website=dirteam.com |date= 7 September 2020|access-date=14 February 2021 |url= https://dirteam.com/sander/2020/09/07/robocopy-supports-copying-files-over-smb-with-compression-on-windows-server-2019-and-beyond/ }}</ref><ref>{{Cite web |title=SMB Compression Lowers Bandwidth and Improves Copy Times in Windows Server and Azure|last=Smith |first=Russell |work=Petri |date=27 November 2020 |url= https://petri.com/smb-compression-lowers-bandwidth-and-improves-copy-times-in-windows-server-and-azure}}</ref>

==Examples of use==
Here are some examples of usage, which is not case-sensitive. If more than one option is specified, they must be separated by spaces.

;Example 1
:Copy directory contents of the source {{code|Directory A}} to the destination {{code|Directory B}} (including file data, attributes and timestamps), recursively with empty directories (<code>/E</code>):

:<syntaxhighlight lang="bat">Robocopy "C:\Directory A" "C:\Directory B" /E</syntaxhighlight>

:If directory names have non-standard characters, such as spaces, they must be enclosed in double quotes, as is usual in the command line.

;Example 2
:Copy directory [[Recursion (computer science)|recursively]] (<code>/E</code>), copy all file information (<code>/COPYALL</code>, equivalent to <code>/COPY:DATSOU</code>, <code>D</code>=Data, <code>A</code>=Attributes, <code>T</code>=Timestamps, <code>S</code>=Security=[[NTFS]] [[Access control list|ACL]]s, <code>O</code>=Owner info, <code>U</code>=Auditing info), do not retry locked files (<code>/R:0</code>) (the number of retries on failed copies default value is 1 million), preserve original directories' Timestamps (<code>/DCOPY:T</code> - requires version XP026 or later):

:<syntaxhighlight lang="bat">Robocopy C:\A C:\B /COPYALL /E /R:0 /DCOPY:T</syntaxhighlight>

;Example 3
:Mirror A to B, destroying any files in B that are not present in A (<code>/MIR</code>), copy files in resume mode (<code>/Z</code>) in case network connection is lost:

:<syntaxhighlight lang="bat">Robocopy C:\A \\backupserver\B /MIR /Z</syntaxhighlight>

:For the full reference, see the Microsoft TechNet Robocopy page.<ref>{{cite web|url=https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy|title=Robocopy |website=Microsoft Technet |date=7 June 2020}}</ref>

===Syntactic focus on copying folders===
Robocopy syntax is markedly different from its predecessors ([[copy (command)|copy]] and [[XCOPY|xcopy]]), in that it accepts only folder names, without trailing backslash, as its source and destination arguments. File names and [[wildcard character]]s (such as <code>*</code> and <code>?</code>) are not valid as source or destination arguments; files may be selected or excluded using the optional "file" filtering argument (which supports wildcards) along with various other options.<ref>{{cite web |title=Robocopy |url=https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/cc733145(v=ws.11) |website=Microsoft Docs |publisher=[[Microsoft]] |access-date=14 January 2019 |date=31 October 2016}}</ref>

For example, to copy two files from folder  <code>c:\bar</code> to <code>c:\baz</code>,  the following syntax is used:

<syntaxhighlight lang="bat">robocopy c:\bar c:\baz file1.txt file2.db</syntaxhighlight>

And to copy all PDF files from <code>c:\bar</code> to <code>c:\baz</code>:

<syntaxhighlight lang="bat">robocopy c:\bar c:\baz *.pdf</syntaxhighlight>

The files named are copied only from the folder selected for copying; fully qualified path names are not supported.

CAUTION: A long-standing issue with Robocopy means that if you back up from the root folder of a drive [ e.g., {{code|robocopy d:\    b:\d-backup\ ....}}], the destination files will be given attributes including SH. This means that they will be invisible to normal access (including DIR in cmd.exe). To fix this, add {{code|/a-:SH}} to the robocopy command line - or do an ATTRIB command to remove them afterwards.

==Output==
Robocopy outputs to the screen, or optionally to a log file, the names of all the directories it encounters, in alphabetical order. Each name is preceded by the number of files in the directory that fulfill the criteria for being copied. If the directory does not yet exist in the target, it is marked "New Dir"; if the directory is empty and the /E option is not used, or it contains no files meeting the criteria, a new directory will not be created.

If the /NFL (no file names in log) option is not used, the files being copied will be listed after the name of the directory they are in.

At the end of the output is a table giving numbers of directories, files, and bytes. For each of these, the table gives the total number found in the source, the number ''copied'' (including directories marked "New Dir" even if they are not copied), the number ''skipped'' (because they already exist in the target), and the number of ''mismatches'', ''FAILED'', and ''extras''. "Failed" can mean that there was an I/O error that prevented a file being copied, or that access was denied. There is also a row of time taken (in which the time spent on failed files seems to be in the wrong column).

==Bandwidth throttling==
Robocopy's "[[Interframe gap|inter-packet gap]]" (IPG) option allows some control over the network bandwidth used in a session. In theory, the following formula expresses the delay ({{Mvar|D}}, in milliseconds) required to simulate a desired bandwidth ({{mvar|B<sub>D</sub>}}, in [[kilobits per second]]), over a network link with an available bandwidth of {{mvar|B<sub>A</sub>}} kbps:

:<math>D = {B_A - B_D \over B_A \times B_D} \times 512 \times 1000</math>

In practice however, some experimentation is usually required to find a suitable delay, due to factors such as the nature and volume of other traffic on the network. The methodology employed by the IPG option may not offer the same level of control provided by some other bandwidth throttling technologies, such as [[Background Intelligent Transfer Service|BITS]] (which is used by [[Windows Update]] and BranchCache).

==Limitations==
* Robocopy does not copy open files. Any process may open files for exclusive read access by withholding the <code>FILE_SHARE_READ</code><ref>
{{cite web
    | url = https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea
    | title = CreateFile function
    | website = Windows App Development
    | date = 9 February 2023
 | via = [[Microsoft Learn]]
    | publisher = Microsoft
    | quote = FILE_SHARE_READ [...] Enables subsequent open operations on a file or device to request read access. Otherwise, other processes cannot open the file or device if they request read access.
}}</ref> flag during opening. Normally [[Shadow Copy|Volume Shadow Copy Service]] is used for such situations, but Robocopy does not use it. Consequently, Robocopy is not suitable for backing up live operating system volumes. However, a separate utility such as ShadowSpawn<ref>{{cite web
    | url = https://github.com/candera/shadowspawn
    | title = ShadowSpawn
    | publisher = Craig Andera
    | quote = ShadowSpawn.exe is an open source MIT licensed tool that creates and manages shadow copies.
    | access-date = 2015-07-14
}}</ref> (under MIT License) or DiskShadow<ref>{{cite web
    | url = http://technet.microsoft.com/library/cc772172(v=ws.10).aspx
    | title = Diskshadow
    | date = 18 April 2012
 | publisher = Microsoft TechNet
    | quote = DiskShadow.exe is a tool that exposes the functionality offered by the Volume Shadow Copy Service (VSS).
    | access-date = 2013-03-06
}}</ref> (included with [[Windows Server 2008]]), can be used beforehand to create a shadow copy of a given volume, which Robocopy can then back up.

* Robocopy versions on systems older than Windows Vista do not mirror properly. They ignore changed security attributes of previously mirrored files.<ref>{{cite web|url=http://www.zdnet.com.au/blogs/snorage/soa/Microsoft-s-Robocopy-compromise/0,2000064373,339291041,00.htm|title=Microsoft's Robocopy compromise|date=2008-08-04|publisher=ZDNet|archive-url=https://web.archive.org/web/20100317020028/http://www.zdnet.com.au/blogs/snorage/soa/Microsoft-s-Robocopy-compromise/0,2000064373,339291041,00.htm|archive-date=March 17, 2010|url-status=dead|access-date=2012-11-11}} 
</ref><ref>{{cite web|url=http://msmvps.com/blogs/martinzugec/archive/2008/03/03/ugly-bug-in-robocopy-ignoring-security-on-file-level.aspx|title=Ugly bug in Robocopy - ignoring security on file level - Martin Zugec blog|date=2008-03-03|publisher=Msmvps.com|access-date=2012-11-11}}</ref>
* When specifying the <code>/MT[:n]</code> option to enable multithreaded copying, the <code>/NP</code> option to disable reporting of the progress percentage for files is ignored. By default the MT switch provides 8 threads. The n is the number of threads you specify if you do not want to use the default.<ref>{{cite web|url=http://social.technet.microsoft.com/Forums/windows/en-US/e8c38fe1-df36-4dfc-8dd5-50613b1a7984/robocopys-mt-option-disables-np-option?forum=w7itprogeneral&prof=required|title=Robocopy's /MT option disables /NP option|date=2009-12-13|publisher=Microsoft TechNet|access-date=2014-02-26}}</ref>

==GUI==
Although Robocopy itself is a command-line tool, [[Microsoft TechNet]] provided a [[GUI]] front-end called Robocopy GUI. It was developed by Derk Benisch, a systems engineer with the [[MSN Search]] group at Microsoft, and required [[.NET Framework]] 2.0.<ref>{{cite news |author=Joshua Hoffman|title=Utility Spotlight Robocopy GUI|url=https://technet.microsoft.com/en-us/magazine/cc160891.aspx|work=TechNet Magazine|publisher=Microsoft Corporation and CMP Media, LLC|date= November 2006|access-date=2008-07-17 }}</ref> It included a copy of Robocopy version XP026. It is no longer available from Microsoft, but may be downloaded from the [[Internet Archive]]'s [[Wayback Machine]].<ref>{{cite web |title=Is Microsoft's Robocopy GUI still available |url=https://www.tenforums.com/software-apps/176362-microsofts-robocopy-gui-still-available.html |website=Windows TenForums |access-date=2 May 2022}}</ref>

There are non-Microsoft GUIs for Robocopy:
* RoboCopy GUI by PC Assist Software v3.0 (includes job scheduling) (April 19, 2024) <ref>{{Cite web |last=Rose |first=Darren |title=PC Assist Software - RoboCopy GUI |url=https://www.pcassistsoftware.co.uk/robocopygui.html |access-date=2024-03-08 |website=www.pcassistsoftware.co.uk}}</ref>
* Cinchoo's ChoEazyCopy, Simple and powerful RoboCopy GUI v2.0.0.1 (March 11, 2022)<ref>{{Cite web |title=Cinchoo's ChoEazyCopy |author=Cinchoo |website=GitHub |date=11 March 2022 |url= https://github.com/Cinchoo/ChoEazyCopy/releases/}}</ref>
* "Easy RoboCopy", latest version 1.0.16 released on January 11, 2022.<ref>{{cite web|url=http://www.tribblesoft.com/home-page/easy-robocopy/ |title=Easy RoboCopy |publisher=TribbleSoft |access-date=2022-05-02}}</ref>
* "WinRoboCopy" revision 1.3.5953.40896 released on April 19, 2016.<ref>{{cite web|url=http://www.upway2late.com/projects/winrobocopy |title=WinRoboCopy - UpWay2Late.com Software |publisher=Upway2late.com |access-date=2012-11-11}}</ref>
* RoboCop RoboCopy, Robocopy GUI Skin and script generator with Progress Monitoring, 10 September 2015.<ref>{{Cite web |title=RoboCop RoboCopy |author=turnssoft |website=SourceForge |date=10 September 2015 |url= https://sourceforge.net/projects/robocoprobocopy/}}</ref>
* A program by SH-Soft, also called "Robocopy GUI" v1.0.0.24 (October 8, 2005).<ref>{{cite web|url=https://www.sh-soft.com/en/tools/robocopy-gui/index.html |title=SH-RoboCopy GUI |publisher=SH-Soft |access-date=2012-11-23}}</ref>
Ken Tamaru of Microsoft developed a copying program with functionality similar to Robocopy, called [[RichCopy]], this was discontinued in 2010. It is not based on Robocopy, and does not require .NET Framework.<ref>{{cite news |last=Hoffman |first=Joshua |date=November 2006 |title=Free Utility: RichCopy, an Advanced Alternative to RoboCopy |url=https://technet.microsoft.com/en-us/magazine/2009.04.utilityspotlight.aspx |access-date=2008-07-17 |work=TechNet Magazine |publisher=Microsoft Corporation and CMP Media, LLC}}</ref>

==Versions==

All versions of Robocopy store their version number and release date in their executable file header, viewable with [[File Explorer]] or [[PowerShell]]. Some of them (not all) report their version numbers in their textual output.

{| class="wikitable"
|-
! Product version !! File version !! Year !! Bundled with
|-
| 1.54
| {{sdash}} || 1996 || Windows NT 4.0 [[Windows Resource Kit|Resource Kit]]
|-
| 1.70
| {{sdash}} || 1997 || Windows NT Resource Kit
|-
| 1.71
| 4.0.1.71 || 1997 || Windows NT Resource Kit
|-
| 1.95
| 4.0.1.95 || 1999 || Windows 2000 Resource Kit
|-
| 1.96
| 4.0.1.96 || 1999 || Windows 2000 Resource Kit
|-
| XP010
| 5.1.1.1010 || 2003 || Windows 2003 Resource Kit
|-
| XP026
| 5.1.2600.26 || 2005 || Robocopy GUI v.3.1.2
|-
| XP027
| 5.1.10.1027 || 2008 || [[Windows Vista]], [[Windows Server 2008|Server 2008]], [[Windows 7|7]], [[Windows Server 2008 R2|2008 R2]]
|-
| 6.1
| 6.1.7601 || 2009 || [http://support.microsoft.com/kb/2639043 KB2639043]
|-
| colspan = 3 {{N/A|Same as Windows}}
| [[Windows 8]] and later, [[Windows Server 2012]] and later
|}

==See also==
* [[List of file copying software]]
* Command line
** [[List of DOS commands]]
** [[rsync]]
* GUI
** [[SyncToy]]
** [[Ultracopier]]

==References==
{{Reflist}}

==External links==
{{Wikibooks|Guide to Windows Commands}}
* [https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy Robocopy documentation] on [[Microsoft Learn]]
* [https://ss64.com/nt/robocopy.html RoboCopy documentation] on SS64.com

{{Windows commands}}

[[Category:File copy utilities]]