This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Download Microsoft Edge
More info about Internet Explorer and Microsoft Edge
Windows setup scripts
Setupcomplete.cmd
and
ErrorHandler.cmd
are custom scripts that run during or after the Windows Setup process. They can be used to install applications or run other tasks by using
cscript/wscript
scripts.
%WINDIR%\Setup\Scripts\SetupComplete.cmd
: This script runs with local system permissions and starts immediately after the user sees the desktop. This setting is disabled when using OEM product keys, except on Enterprise editions and Windows Server operating systems.
%WINDIR%\Setup\Scripts\ErrorHandler.cmd
: This script runs automatically when Setup encounters a fatal error. It runs with local system permission.
Run a script after setup is complete (SetupComplete.cmd)
Order of operations
After Windows is installed but before the logon screen appears, Windows Setup searches for the
SetupComplete.cmd
file in the
%WINDIR%\Setup\Scripts\
directory.
If a
SetupComplete.cmd
file is found, Windows Setup runs the script. Windows Setup logs the action in the
C:\Windows\Panther\UnattendGC\Setupact.log
file.
Setup does not verify any exit codes or error levels in the script after it executes
SetupComplete.cmd
.
Warning
You can't reboot the system and resume running
SetupComplete.cmd
. You should not reboot the system by adding a command such as
shutdown -r
. This will put the system in a bad state.
If the computer joins a domain during installation, the Group Policy that is defined in the domain is not applied to the computer until
Setupcomplete.cmd
is finished. This is to make sure that the Group Policy configuration activity does not interfere with the script.
Run a script if Windows Setup encounters a fatal error (ErrorHandler.cmd)
ErrorHandler.cmd is useful when you're installing many systems at the same time. This helps you detect when an error occurs during Windows Setup. When it does, Setup automatically runs a script that can contain custom commands or actions to address the cause of the error.
If Windows Setup encounters a fatal error and is prevented from completing the installation, Windows Setup searches for a command script in the following directory:
%WINDIR%\Setup\Scripts\ErrorHandler.cmd
. One of two actions will occur, depending on whether the script is found.
If the script is not found, a dialog box is displayed with the error text. A user must dismiss the dialog box before Windows Setup exits.
If the script is found, the script executes synchronously. No dialog box or error text is displayed. After the
ErrorHandler.cmd
script has finished running, Windows Setup exits.
Depending on the phase of Windows Setup, the computer will return to the environment from which Windows Setup was executed, such as an earlier version of the operating system or Windows Preinstallation Environment (Windows PE), for example.
There may be instances when Windows Setup encounters more than one error and runs the ErrorHandler.cmd script more than once. When developing the code for
ErrorHandler.cmd
, make sure that you can run this script multiple times.
Use ErrorHandler.cmd
To use ErrorHandler.cmd, you can do either of the following:
Mount the image, and add it to the image, in
%WINDIR%\Setup\Scripts\ErrorHandler.cmd
. Unmount the image.
Add
ErrorHandler.cmd
to a temporary file location (for example, C:\Temp\ErrorHandler.cmd), and then run Windows Setup using the
/m
option.
Setup /m:C:\Temp
To learn more, see Windows Setup Command-Line Options.
Use Unattend to run scripts
Create an Unattend.xml file with one of these settings to run during the Windows Setup process. This can be used with OEM product keys.
To run services or commands that can start at the same time, use RunAsynchronousCommands.
Some of these settings run in the user context, others run in the system context depending on the configuration pass.
Add Microsoft-Windows-Setup\RunAsynchronousCommand or RunSynchronousCommand to run a script as Windows Setup starts. This can be helpful for setting hard disk partitions.
Add Microsoft-Windows-Deployment\RunAsynchronousCommand or RunSynchronousCommand to the auditUser configuration pass to run a script that runs when the PC enters audit mode. This can be helpful for tasks like automated app installation or testing.
Add Microsoft-Windows-Shell-Setup\LogonCommands\AsynchronousCommand or FirstLogonCommands\SynchronousCommand to run after the Out of Box Experience (OOBE) but before the user sees the desktop. This can be especially useful to set up language-specific apps or content after the user has already selected their language.
Use these scripts sparingly because long scripts can prevent the user from reaching the Start screen quickly. For retail versions of Windows, additional restrictions apply to these scripts. For info, see the Licensing and Policy guidance on the OEM Partner Center.
When you add a script using FirstLogonCommands, it will be triggered on the next boot, even if you boot into audit mode using Ctrl+Shift+F3. To boot to audit mode without triggering these scripts, add the setting: Microsoft-Windows-Deployment\Reseal\Mode = Audit.
Windows Setup Technical Reference
Deploy a Custom Image
Boot Windows to Audit Mode or OOBE
Add Device Drivers to Windows During Windows Setup
