How do I run a command on a new EC2 Windows instance at launch?

3 minute read

I want to run a custom script when I launch a new Amazon Elastic Compute Cloud (Amazon EC2) Windows instance.

Short description

When you launch an instance in Amazon EC2, you have these options:

  • Pass the user data to the instance to perform common automated configuration tasks
  • Run scripts after the instance starts

Add the script to the user data if you want to run a script that starts when the instance launches. The user data is processed by EC2Config (Windows Server, 2012 R2 and earlier), EC2Launch, or EC2Launch V2 (Windows Server, 2016 and later).


When you add a script to the user data, enclose it within a special tag. This tag determines whether the commands run in a command prompt window or use the Windows PowerShell. For more information, see Run commands on your Windows instance at launch.

To run a custom script at startup, specify its user data when you launch and configure the new EC2 Windows instance. In a standard configuration, an AWS Windows Amazon Machine Images (AMI) can be activated to run the user data during its initial launch.

Create a custom script to run user data at startup

You can specify if you want the user data scripts to run the next time the instance reboots or restarts. Or, you can specify that user data scripts run every time the instance reboots or restarts. Follow these steps to create a custom script:

  1. Open the Amazon EC2 console, and then choose AMIs from the navigation pane.

  2. Select an AMI, and then choose Launch.

  3. Select an instance type. Then, choose Next: Configure Instance Details.

  4. For Advanced Details, enter your custom script in the User data text box.

    The custom script has the flexibility to run as a batch script, Windows PowerShell script, YAML configuration script, and Base64 encoding. To allow scripts to run, enclose the script in a specific tag when adding it to user data. For example you can specify a Windows PowerShell script using the powershell tag. For more information on Script type and sample script syntax, see User data scripts.
    Note: The user data doesn't automatically run after the initial launch. If a script includes the persist tag, then the launch runs the user data during subsequent reboots or starts.

  5. Add the following command to run the user data scripts every time you reboot or restart the instance:

  6. Complete the launch wizard to start the instance.

Note: You have the option to run a custom script on an existing Amazon EC2 Windows instance. For more information see How do I run a command on an existing EC2 Windows instance when I reboot or start the instance?

Review the logs

For additional troubleshooting, EC2Launch, EC2Launch V2, and EC2Config log files contain the output from the standard output and standard error streams. You can find log files in the following locations:

  • EC2Launch: C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log
  • EC2Launch V2: C:\ProgramData\Amazon\EC2Launch\log\agent.log
  • EC2Config: C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2Config.log
AWS OFFICIALUpdated 8 months ago