How do I use EC2Launch to run a user data script on my EC2 Windows instance?

3 minute read

I want to use EC2Launch to run a user data script on my Amazon Elastic Compute Cloud (Amazon EC2) Windows instance.


By default, user data execution is turned on for the initial launch of all Windows Amazon Machine Images (AMIs). For more information, see Run commands on your Windows instance at launch.

When you add the script to user data, you must enclose the script in a special tag. This tag determines whether the commands run in a command prompt window or use Windows PowerShell. For more information, see User data scripts.

Note: Before you begin, make sure that you meet the prerequisites to work with instance user data.

Use an AMI at instance launch to run the user data script

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

  2. Select an AMI, and then choose Launch instance from AMI.

  3. Select an instance type, and then choose Launch instance.

  4. Choose Key pair (Login) - For Key pair name, and then select an existing key pair. Or, create a new key pair. For more information, see Amazon EC2 key pairs and Windows instances.

  5. In Network settings and Configure storage, choose your preferred settings for your instance type.

  6. Expand Advanced Details, and then upload or enter your user data in User data.

  7. (Optional) To run the user data scripts every time you reboot or start the instance, add this command:

  8. Choose Launch instance.

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 these 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

Configure a custom AMI to run user data at instance launch

To create a custom Windows AMI that runs user data at instance launch, configure the user data to run at the next startup. When you create the custom AMI, choose either Shutdown with Sysprep or Shutdown without Sysprep. You can then reuse the custom AMI with user data turned on for instances that you launch from the custom AMI. For more information, see How can I use Sysprep to create and install custom reusable Windows AMIs?

  1. Connect to your EC2 instance, and then check whether EC2Launch is installed with this Windows PowerShell command:

    Test-ModuleManifest -Path "C:\ProgramData\Amazon\EC2-Windows\Launch\Module\Ec2Launch.psd1" | Select Version
  2. If the EC2Launch isn't installed, then install the latest version.

  3. Turn on user data execution with EC2Launch (Windows Server 2016 or later).

For more information, see View and update the instance user data.

Related information

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

How do I run a command on an existing EC2 Windows instance when I reboot or start the instance?

AWS OFFICIALUpdated 7 months ago