# aws ec2 run-instances

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws ec2 run-instances launches one or more new instances from an AMI. The minimum is --image-id, --instance-type and usually --subnet-id, --security-group-ids and --key-name; add --tag-specifications to name it at launch and --metadata-options HttpTokens=required to enforce IMDSv2.

## What the command does

`run-instances` is the single API behind every EC2 launch, including the console wizard. It returns as soon as EC2 has accepted the request, with each new instance in `pending`. Everything you do not specify comes from the launch template (if you pass one), the AMI, or account defaults such as the default VPC.

The call is all-or-nothing on count: if EC2 cannot launch at least the minimum number you ask for, it launches none.

## Syntax

```
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type t3.micro \
  [--count 1] \
  [--subnet-id subnet-0123456789abcdef0] \
  [--security-group-ids sg-0123456789abcdef0] \
  [--key-name my-key] \
  [--iam-instance-profile Name=my-instance-profile] \
  [--tag-specifications ...] [--user-data file://init.sh] \
  [--launch-template LaunchTemplateName=web,Version=\$Latest]
```

`--count` is a CLI shortcut for the API's `--min-count`/`--max-count`: `--count 3` means exactly three, `--count 2:5` means at least two and up to five.

## Worked examples

**A complete, production-shaped launch** with the latest Amazon Linux 2023 AMI resolved from Parameter Store, a Name tag on both the instance and its volume, IMDSv2 required and a 30 GiB gp3 root disk:

```
aws ec2 run-instances \
  --image-id resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64 \
  --instance-type t3.small \
  --subnet-id subnet-0123456789abcdef0 \
  --security-group-ids sg-0123456789abcdef0 \
  --iam-instance-profile Name=app-ec2 \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --block-device-mappings '[{"DeviceName":"/dev/xvda","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=web-1}]' \
                       'ResourceType=volume,Tags=[{Key=Name,Value=web-1-root}]' \
  --user-data file://init.sh \
  --query "Instances[].InstanceId" --output text
```

The CLI base64-encodes the user data file for you; passing an already-encoded file double-encodes it and the script silently never runs.

**Launch from a launch template, overriding only the type:**

```
aws ec2 run-instances \
  --launch-template LaunchTemplateName=web,Version='$Default' \
  --instance-type m7i.large
```

**Launch a Spot instance:**

```
aws ec2 run-instances --image-id ami-0123456789abcdef0 --instance-type c7i.large \
  --instance-market-options MarketType=spot \
  --subnet-id subnet-0123456789abcdef0
```

**Launch and wait until it is reachable:**

```
ID=$(aws ec2 run-instances --image-id ami-0123456789abcdef0 --instance-type t3.micro \
  --subnet-id subnet-0123456789abcdef0 --query "Instances[0].InstanceId" --output text)
aws ec2 wait instance-status-ok --instance-ids "$ID"
```

## Errors you will meet

| Error | What to check |
|---|---|
| `InvalidAMIID.NotFound` | AMI IDs are per region; the ID came from another region or the AMI is private to another account. |
| `VPCIdNotSpecified` / no default subnet | The region has no default VPC; pass `--subnet-id`. |
| `InvalidKeyPair.NotFound` | Key pairs are per region too. |
| `InsufficientInstanceCapacity` | Try another AZ (subnet) or instance type. |
| `VcpuLimitExceeded` | Request a higher On-Demand vCPU quota in Service Quotas. |
| `UnauthorizedOperation` | Besides `ec2:RunInstances`, you need `iam:PassRole` for an instance profile and `ec2:CreateTags` for tag-on-create. |

## Gotchas

- **Security group IDs vs names.** `--security-groups` takes names and only works in the default VPC; use `--security-group-ids` everywhere else.
- **Public IP.** Whether the instance gets one depends on the subnet setting. Override it with `--associate-public-ip-address` or `--no-associate-public-ip-address`.
- **Retries can double-launch.** Pass a unique `--client-token` so a retried request does not create a second instance.
- **Stopping on OS shutdown.** Set `--instance-initiated-shutdown-behavior stop` explicitly if your user data might call `shutdown`; `terminate` deletes the instance.

## Questions

### How do I create an EC2 instance with a name from the CLI?

The Name is just a tag. Add --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=web-1}]' to run-instances so it is named from the moment it launches.

### How do I list running instances after launching?

Use aws ec2 describe-instances --filters "Name=instance-state-name,Values=running" with a --query that picks InstanceId and the Name tag.

### How do I keep an EC2 instance running after I close SSH?

The instance keeps running regardless of your SSH session. It is processes started in your shell that stop; run them as a systemd service or under tmux, screen or nohup.

## When this happens away from your desk

Launching capacity is rarely something you want to do from a phone, but seeing that a launch happened is. CloudConsole, a phone app for AWS, is built to show new and existing resources alongside their alarms and costs.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: ec2 run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html)
- [RunInstances API reference](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html)

## Related

- [aws ec2 describe-instances](https://cloudconsole.dev/cli/ec2-describe-instances)
- [aws ec2 create-key-pair](https://cloudconsole.dev/cli/ec2-create-key-pair)
- [aws ec2 describe-images](https://cloudconsole.dev/cli/ec2-describe-images)
- [InvalidAMIID.NotFound: The image id does not exist](https://cloudconsole.dev/errors/ec2-invalidamiid-notfound)
- [VcpuLimitExceeded: You have requested more vCPU capacity than your current vCPU limit](https://cloudconsole.dev/errors/ec2-vcpulimitexceeded)
- [InsufficientInstanceCapacity: We currently do not have sufficient capacity](https://cloudconsole.dev/errors/ec2-insufficientinstancecapacity)

---

Source: https://cloudconsole.dev/cli/ec2-run-instances

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
