The Ultimate Guide to Robocopy

Always use unc paths not drive letters

A reader on Reddit discovered the hard way to not use mapped drives as a destination directory. Instead, always use always use a UNC path. You might run into issues with the 256-character limit if you do. Check out this Microsoft doc for more information.

Asynchronous copying (robocopy /mt)

By default, robocopy only processes one file at a time. However, you can force robocopy to copy more files than at once by using the /MT option.

The /MT option allows you to specify the number of threads robocopy will use to copy files. The maximum is 128.

You can use /MT like so:

I’ve chosen 32 in this case as a baseline. I suggest starting at 32 to see how your computer and network handle things and adjust the threads accordingly.

Note that if you do use /MT, you won’t be able to use /IPG or /EFSRAW. For better performance, don’t output the log to the console. Instead, use /LOG.

By directory name

Robocopy allows you to filter items not just by file but by directory name too. Using robocopy /xd, you can exclude certain directories matching a specific name.

When copying multiple folders, use the /XD switch to exclude folders from the run.

By file name or file extension

Filtering what files get copied/moved in a robocopy call is done using wildcards. You can use a wildcard to filter on files matching a specific file name string or extension.

For example, to only copy TXT files, you can specify *.txt.

If you’d like to limit to only files starting with a, you could use a*.

Y0u can also provide multiple sets of file name matches by separating them with a space as shown below.

When you filter by file name, robocopy will show you the filter in the output.

By file/directory timestamp

Below you will find all of the robocopy options that will exclude files and folders based on various timestamp attributes.

SwitchExplanation
/DCOPY:TCopy directory timestamps
/MAXAGE:nExclude files older than n days/date
/MINAGE:nExclude files newer than n days/date
/XOIf destination file exists and is the same date or newer than the source, don’t overwrite
/XNIf destination file exists and is the same date or older than the source, don’t overwrite

There are two popular options to choose when filtering on things like timestamp; /XO and /MAXAGE.

/XO allows you to exclude files from copy only if they are newer than the source. Using the /XO option, you can robocopy only new files by access date.

If you know the maximum age files will be, you can also use the /MAXAGE option. This allows you to specify in YYYMMDD format the older date a file can have before it’s copied.

Changing the exit code in a batch file

If you’re executing robocopy with a batch file, you can find the value of the %ERRORLEVEL% variable. If it returns 1 then use the exit keyword to exit the script with 0.

Changing the exit code in a powershell script

If you’re executing robocopy in a PowerShell script, you can invoke robocopy with Start-Process using PassThru to return the process created and Wait to wait for robocopy to finish. You can then check the ExitCode property for a value of 1. If the exit code is 1 then exit the PowerShell script with a 0 using $host.SetShouldExit().

Common errors

If you’re dealing with thousands of files, you’re bound to run across some problems. Here’s a breakdown of common errors I’ve come across

Common robocopy syntax reference

Why such a long blog post on a single utility? Just feast your eyes on the tables below. You have a lot of options to copy or move files with robocopy! You will more options in the individual sections.

These tables were built from the help syntax returned from robocopy /?. They’ve been broken up into more meaningful sections, added to over time, and cleaned up to provide more useful info.

Copying files over a network

If you’re copying files over a network, there are a few options that you should consider.

Robocopy allows you to copy files in ‘restartable mode’ using the /Z option. This means that if a file begins copying and fails midway, the copy can start again instead of failing completely. The /Z option is useful when the stream gets cut over a network.

Warning: Some have reported using /Z cuts performance by 1/4. Let me know your findings.

You can also use the /FFT option. This switch has been known to more accurately preserve file timestamps when transferring over a network. This option uses FAT file system timestamps instead of NTFS.

Creating a job file without running a job using /quit

The purpose of the /QUIT option isn’t obvious. On the surface, you may think /QUIT forces a running to exit. Instead, /QUIT acts more like an option to prevent a job from running in the first place.

Officially, the /QUIT option “forces robocopy to terminate processing the command line”. However, it would be better explained as creating a job file without running a job.

If you use the /SAVE option, it will also run the job automatically. There’s no way to create a job file without first running the job. You could create the RCJ job file with a text editor or you could use robocopy do it by appending /QUIT to the end.

Destination options

SwitchExplanationDefault BehaviorEquivalent SwitchNotes
/A :[RASHCNET]Set file attribute(s) on destination files add
/A-:[RASHCNET]Remove file attribute(s) on destination files
/FATCreate destination files using 8.3 FAT file names only
/CREATECreate directory tree structure zero-length files only
/DSTCompensate for one-hour DST time differences

Editing a job file

Since job files are just text files, you could edit them with your favorite text editor or you could have robocopy do it for you.

You can edit job files using a combination of /JOB, /SAVE and /QUIT.

For example, perhaps you’d like to exclude all EXE files from your robocopy job saved in a job file called backupfiles.rcj. You’ve already created the job file and don’t want to overwrite the entire thing. You can add the new option like below:

:/>  Курсор мышки постоянно показывает загрузку: устранение проблемы

Error invalid parameter

When you see an error stating error invalid parameter, this normally means that you’ve tried to pass options to robocopy out of sequence somehow. The robocopy invalid parameter 3 error is the most common, it seems.

A common reason you’d receive this error is when you specify a source or destination directory with spaces and forget to surround it with quotes.

Exit codes

Like all other command-line utilities, robocopy returns exit codes depending on the results of the execution. We all wish for robocopy to always exit successfully with a 0 but that doesn’t always happen.

Below you will find all of the exit code that robocopy returns and their explanation. Any exit code greater than seven indicates at least one failure during execution.

Exit CodeExplanation
No action performed. Source and destination are synchronized.
1At least one file was copied successfully.
2Extra files or directories were detected. Examine log.
3Exit codes 2 and 1 combined.
4Mismatched files or directories found. Examine log.
5Exit codes 4 and 1 combined.
6Exit codes 4 and 2 combined.
7Exit codes 4, 1 and 2 combined.
8At least one file or directory could not be copied. Retry limit exceeeded. Examine log.
16Copy failed catastrophically.

Note that if you’re executing robocopy in a third-party utility, that utility may think any non-zero exit code is a failure. To prevent this, you can change the exit code to 0 if it returns 1.

The Robocopy “extra” file exit code is a common return code meaning an “extra” file is in the destination folder but not the source folder. This code excludes extras that will prevent any deletions from the destination.

Filtering files and folders

The large majority of the options available to you are to exclude files and directories many different ways. I’ve broken down all of the ways you can filter or exclude files and directories based on various criteria.

Find the directory size of a network folder

Contributor: northendtroooper (Reddit)

Limiting log elements with /njs and /njh

By default, robocopy returns two elements in it’s output, a job header and a job summary.

The job header is the simple ROBOCOPY header at the top.

The job summary shows a summary status of all files/folders, how much data was transferred and the time the run ended.

Monitoring options

SwitchExplanationDefault BehaviorEquivalent SwitchNotes
/R:nNumber of retries on failed copies/R:1000000Always try to set this option. I recommend setting this to 10-20 to not waste time retrying.
/W:nWait time between retries/W:30Always try to set this option to a lower number to retry more quickly. I suggest 5-10.
/REGSave /R:n and /W:n in the Windows registry as default settings
/RH:hhmm-hhmmtimes when new copies can be started
/TBDWait for sharenames to be definedretry error 67
/PFCheck run hours on a per file (not per pass) basis
/MON:nRun again when more than n changes seen
/MOT:mRun again in m minutes, if changed

Quickly delete folder contents (ignoring permissions on subfolders)

Contributor: pizzasteveo (Reddit)

Recognize default options

Robocopy uses a lot of options by default. You can pick them out by looking at the tables above. It also provides a handy output to every time you run the utility.

You can see below that when I ran robocopy with its most basic options (the source and destination folder), it automatically used some options. Understanding the default behavior is important.

Reference the options you see in the output with the option explanations above and you’ll understand exactly what robocopy is doing under the covers.

Redirecting output log to a file

If you need to save the output log, you can redirect it to a text file and/or display it on the console. You can do so using traditional output redirectors like >, >>, PowerShell or the /LOG option.

To redirect the output log to a file using the /LOG option overwriting any existing log file use the syntax /LOG:<filepath> like below. The only output you will receive on the console is the path to the log file.

If you’d like to keep the contents of any existing log file and append results to a file, you can use the operator as shown below.

Redirecting output log to a file and displaying on the console

If you’d like to save the output log to a file yet also see it on the console, you can use the /TEE option. This option causes robocopy to write the output to the log file while still maintaining the default behavior of returning output to the console.

Robocopy alternatives

Robocopy is an awesome tool but there are so many other tools similar to it that may be of interest.

Get an interactive Choose Your Own Cloud Adventure E-Book to learn how Veeam and AWS can help you fight ransomware, rising cloud costs, and unforeseen data loss, making you a hero!

Robocopy backup mode (robocopy /z)

Robocopy has a option (/B) or as a backup to restartable mode (/ZB) which copies files in backup mode. What is “backup mode” anyway?

Robocopy examples

You can build your own strings of robocopy or you can take what others have learned and use them! In this section, I’ll cover use cases on how to use robocopy to accomplish various things.

Robocopy jobs

You have seen that dozens of options are available to you. It’s easy for these options to soon become unwieldy. Thankfully, you have a better option than memorizing and ensuring all of these options are spot on every time.

Robocopy job files are text files containing one option per line. You’ll typically use robocopy to create these job files. Once created, you can then either use robocopy to modify them or a simple text editor.

You have various robocopy commands that work with jobs.

SwitchExplanationDefault BehaviorEquivalent SwitchNotes
/JOB:jobnameTake parameters from the named job file
/SAVE:jobnameSave parameters to the named job file
/QUITQuit after processing command lineUseful for viewing parameters
/NOSDNo source directory is specified
/NODDNo destination directory is specified
/IFInclude the following files

A typical job file created with robocopy has an RCJ extension and looks like the below snippet. This job file was created by running robocopy C:src D:dst /save:myjob. You can see that you can provide comments in the job file using :: which is most of what this file has.

:/>  How to Run a Program as a Different User (RunAs) in Windows? | Windows OS Hub

Without comments, the file would only contain one option per line.

Robocopy only copies entire directories

Every robocopy execution will have a source and a destination directory. Robocopy copies and moves files by entire directory. It’s not possible to explicitly copy a single file with robocopy. Use copy or PowerShell’s Copy-Item for that.

However, you can robocopy single file with the right filtering which you’ll learn about below. To robocopy a single file file, specify the source and destination directories immediately followed by the file name in the source.

Robocopy templates and using the /nosd and /nodd options

If you’re working with a lot of job files, you can build job files to accept parameters. Robocopy allows you to pass values from the command-line to jobs when they are run. A parameter isn’t a robocopy term but it fits well in this scenario.

You can build robocopy jobs to accept parameters by not specifying a source or destination directory either explicitly using the /NOSD and /NODD options or just not including a source and destination directory at all.

For a simple example, create a job file with no source or destination using the syntax below. This job’s intention is to copy all TXT and EXE files from a source to a destination directory.

On its own, this job will never work because there’s no source or destination directory specified.

When you create a job with no source and destination directory, the job file is automatically created using the /NOSD and /NODD options.

The /NOSD options tells robocopy you did not include a source directory while /NODD indicates you didn’t include a destination directory. This job file is a “template” for other jobs.

But you can pass “parameters” to this job file to provide the source and destination directories.

To use the job file just created to copy files from C:src to C:dst, you can pass these directories directly on the command-line which will then be passed to the job.

Robocopy опции копирования

/sКопировать поддиректории. Пустые директории пропускаются.
/eКопировать поддиректории, включая пустые.
/lev:<N>Копировать только верхние N уровней дерева директорий.
/zКопировать файлы в режиме рестарта.
/bКопировать файлы в Backup режиме.
/zbИспользуется режим рестарта. Если доступ запрещен, то используется Backup режим.
/efsraw

Копировать зашифрованные файлы в EFS RAW режиме.

/copy:<CopyFlags>

Указать какие свойства файлов будут копироваться. Правильные варианты для данной опции :

  • D Data
  • A Attributes
  • T Time stamps
  • S NTFS access control list (ACL)
  • O Owner information
  • U Auditing information

Значение по умолчанию DAT (data, attributes, and time stamps).

/dcopy:TКопировать таймштампы директории.
/secКопировать файлы с security (эквивалент /copy:DAT).
/copyallКопировать всю информацию по файлам (эквивалент /copy:DATSOU).
/nocopyНе копировать информацию по файлам (полезно с опцией /purge).
/secfixФиксировать security на всех файлах, даже пропущенных.
/timfixФиксировать время на всех файлах, даже пропущенных.
/purgeУдалить файлы в папке назначения, которых больше нет в исходной папке.
/mirЗеркалировать дерево директорий (эквивалентно двум опциям /e вместе с /purge).
/movПереместить файлы. Т.е. после копирования будут удалены исходные.
/moveПереместить файлы и директории. Исходники будут удалены.
/a :[RASHCNET]Добавить атрибуты к скопированным файлам. Adds the specified attributes to copied files.
/a-:[RASHCNET]Удалить атрибуты у скопированных файлов.
/createСоздать дерево директории и файлы с нулевым размером.
/fatСоздавать файлы с именами в формате 8.3 как в FAT.
/256Отключить поддержку очень длинных путей (которые больше 256 символов).
/mon:<N>Мониторит исходную папку и если обнаружит больше чем N изменений то начнёт копирование изменённых файлов. Подробнее читайте тут : планировщик в Robocopy.
/mot:<M>Мониторит исходную папку, ищет изменения каждые M минут и начинает копировать если были изменения. Подробнее читайте тут : планировщик в Robocopy.
/rh:hhmm-hhmmУказывает время когда начнется выполнение запланированного копирования. Подробнее читайте тут : планировщик в Robocopy.
/pfChecks run times on a per-file (not per-pass) basis.
/ipg:nSpecifies the inter-packet gap to free bandwidth on slow lines.
/slКопировать символические ссылки, вместо реального файла.

Saving job files

Saving a job file is as simply as appending the /SAVE:<jobname> option to the end of your syntax. Replace <jobname> with the name of the job. The /SAVE option will create a file called <jobname>.rcj in the directory where you ran robocopy.

You must specify /SAVE as the last option. Any options specified after /SAVE will not be added to the job file. Also, note that even if an existing job file already exists, robocopy will always overwrite the existing one. Backup or version control your job files!

Note: If you attempt to use the /MT option when saving to a job file, it will not be in the job file. Let me know if you were able to get this to be included.

Scheduling robocopy

Robocopy has a few ways you can schedule when it runs.

Summary

Robocopy is an excellent tool to copy large sets of files. Whether you’re doing a data migration, keeping folders in sync or simply need a quick way to accurately copy files, robocopy is a great choice.

The basics: copying files

The most basic use of robocopy is using a source and destination directory with no options.

This option will copy all files (excluding subfolders) from C:src to C:dst.

You can also copy everything including subfolders (empty or not) and NTFS permissions. This is, from what I can tell, the method to literally copy everything there is about a directory of files to another directory.

Below I’m copying all NTFS ACLs, file owners, subfolders (including empty ones) and all file attributes. All of this is made possible with just the /E option to include all empty subfolders and  /COPYALL to catch the rest.

:/>  Как сделать загрузочную флешку для установки Windows 10, создать запись установочного образа Виндовс через Rufus и другие программы

The basics: moving files

Moving files transfers files from one directory to another just like copying does. The only difference with a move operation is that the source files are removed after the copy.

To delete files/directories from the source after copying, use the /MOV option. This will remove all files in the specified directory (no subfolders).

You can also use /MOVE to move all files and subfolders.

The basics: performing whatif scenarios

If you’ve got a huge file server somewhere you’d like to migrate and don’t want to take any action yet, you can use robocopy to return what it would have done.

Using the /L option, you can tell robocopy to enumerate all of the files and/or folders you specify and return a list of files it would have copied/moved.

You can use the /L option with any other option. This is a great way to return all of the options robocopy would have used (default or not). It will give you an overall view of what robocopy will do given the options you provided it.

The basics: syncing files

Robocopy allows you to sync two directories. This means either ensuring all files in the destination directory are in the source directory and no more. /MIR will replicate data copying all files in the source not in the destination and delete files in the destination not in the source. Beware!

The output log

Robocopy will always return an output log. Whether that log is displayed via stdout on the console and/or redirected to a log file is up to you.

You’ve got lots of options when displaying robocopy output.

Understanding robocopy behavior

I’ve now completely blew your mind with all of the potential syntax options available to you. Let’s now see all of the different combinations of how we can use this syntax.

I could provide you an enormously long list of robocopy commands with an ever-growing number of switches. But I think it’s better to teach you how to fish. Let’s go over how to put sense out of all of these options.

Understanding what robocopy commands can do

If you’ve used copy or PowerShell’s Copy-Item cmdlets, you’ve probably specified a source and destination and went on about your day. There’s not a whole lot of options you can configure there. These robocopy commands have a default behavior.

But robocopy, on the other hand, understands a lot more and gives you the flexibility to tweak the behavior as much as you want.

It’s important to know robocopy isn’t just aware of the concept of a file or directory. There’s a lot more to a filesystem than that and robocopy supports just about everything.

A file sitting on a filesystem isn’t just a dumb object with a single purpose. There are many different attributes and things that go with the concept of a file. For example, a file has attributes such as:

  • a timestamp (written, modified and accessed)
  • NTFS ACL
  • an owner
  • NTFS auditing information
  • hidden flag
  • archived flag

When you copy or move a file, you have the option to bring all of that stuff along with it, if you want.

Understand that when you run robocopy, you’re not just copying a file, you’re also potentially copying all of the other information with it. It’s important to realize that and to account for it in the options you provide robocopy.

Using /ipg to control inter-packet gap

When copying files over a network, you can use the /IPG switch. This is also known as the inter-packet gap option. This option defines (in milliseconds) the frequency in which robocopy will wait between sending new packets.

Using /rh

Using the /RH option, you can tell robocopy to only run during a specific time. This is great if you have a maintenance window or a time when everyone has gone home for the day.

You can specify a start time and an end time in the format HHMM-HHMM. For example, to invoke robocopy but only allow it to run between the hours of 5PM and 9AM as defined by the system clock, run:

You’ll see that if you invoke robocopy outside of those hours, it will tell you the current time and wait for the start time to run.

Using job files

Once a job is saved into a job file, you can then use the /JOB:<jobname> option to specify the job file to read from. Robocopy reads all of the parameters inside of the job file. It then executes just as if you provided the options directly on the command-line.

Using multiple job files

You can even combine the use of job files too. When specifying multiple job files in the same run, all of the options used in that run will be combined together.

For example, perhaps you have a large list of files to exclude from your backupfiles copy job. Open up a text editor, and add the following to create an exclude.rcj file.

You can then exclude these files from the backupfiles job like so:

Since the original backupfiles job file was already excluding all EXE files, the above run’s syntax would look be /XF *.exe a.exe b.txt c.cer. Robocopy combines all options into one.

Опции логов

/lПокажет список файлов которые выбраны для обработки, но само копирование, удаление и т.п. не будет выполняться.
/xСообщает все дополнительные файлы, а не только те, которые выбраны.
/vБолтливый режим. Покажет также пропущенные файлы.
/ts

Покажет таймстампы файлов.

/fpПоказывать полные пути к файлам.
/bytesПоказывать размер файлов в байтах.
/nsУказывает, что размеры файлов не логируются.
/ncУказывает, что классы файлов не должны логироваться.
/nflИмена файлов не будут логироваться.
/ndlИмена директори не будут логироваться.
/npНе будет показываться прогресс копирования. Т.е. количество файлов и директорий.
/etaПоказывает примерное время прибытия копированных файлов.
/log:<LogFile>Логировать в файл. Если такой файл логов уже есть, то он будет перезаписан.
/log :<LogFile>Логировать в файл. Если такой файл логов уже есть, то данные будут добавлены в него.
/unicodeОтображать статус в юникоде.
/unilog:<LogFile>Логировать в файл в формате Unicode. Если такой файл логов уже есть, то он будет перезаписан.
/unilog :<LogFile>Логировать в файл в формате Unicode. Если такой файл логов уже есть, то данные будут добавлены в него.
/teeЛогировать и в файл и в консоль.
/njhУказывает, что нет заголовка задания.
/njsУказывает, что нет резюме работы.

Примеры использования команды robocopy

robocopy c:src c:dst *.txt

В этом примере будут копироваться все файлы .txt из директории c:src в директорию c:dst.

robocopy c:src c:dst /e

Копировать все файлы, включая пустые.

robocopy c:src c:dst /MIR

Сделает зеркало. Использовать с осторожностью т.к. из c:dst будут удалены все файлы которых нет в c:src

robocopy robocopy \computersrc c:dst 

Источник файлов на другом компьютере в сети.

Синтаксис robocopy :

robocopy source destination [file…] [options]

  • source – директория откуда будем копировать. Может быть сетевым путем.
  • destination – директория куда копируем. Локальный или сетевой путь.
  • [file…] – файлы которые нужно скопировать. Можно использоваться wildcard символы (* или ?). Если параметр [file…] не задан, то по умолчанию используется *.*

Syntax depends on the environment

Also, the options you provide to robocopy will depend on the environment. You’ll need to answer a few questions when trying to figure out which options to use.

  • Will you always be copying to an empty directory?
  • Is it possible files may already exist in the destination directory?
  • Will you be copying terabytes of data or just a few megabytes?
  • Will you be copying files over a network or locally?
  • …and more.

If there are no files in the destination file directory, you shouldn’t care about options that overwrite files. If you won’t be copying files over the network, don’t worry about those options. Explicitly define your current and potential future circumstances your environment will be in.

Оставьте комментарий

Adblock
detector