Add a Custom Script to Windows Setup

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

1. After Windows is installed but before the logon screen appears, Windows Setup searches for the SetupComplete.cmd file in the %WINDIR%\Setup\Scripts\ directory.

2. 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.

3. 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.

  -or-

• 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.

  Note

  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.

Related topics

Windows Setup Technical Reference Deploy a Custom Image Boot Windows to Audit Mode or OOBE Add Device Drivers to Windows During Windows Setup