aws ec2 describe-instances: Syntax, Filters & Troubleshooting

aws ec2 describe-instances is an AWS CLI command that retrieves metadata for one or more EC2 instances, supporting server-side filtering, pagination, and JMESPath queries for automation and auditing.

aws ec2 describe-instances --filters Name=instance-type,Values=m5.large

Tested on Ubuntu 22.04 with Linux 5.15.x; verify against vendor docs for non-Debian distributions or older kernels.

Syntax

aws ec2 describe-instances 
  [--instance-ids <value>] 
  [--filters <value>] 
  [--dry-run | --no-dry-run] 
  [--include-managed-resources | --no-include-managed-resources] 
  [--max-items <value>] 
  [--page-size <value>] 
  [--starting-token <value>] 
  [--cli-input-json | --cli-input-yaml] 
  [--no-paginate] 
  [--query <value>] 
  [--output <value>] 
  [--region <value>] 
  [--profile <value>]

Options and Flags

Usage Examples

Example 1: List all running instances with their public IPs

aws ec2 describe-instances 
  --filters "Name=instance-state-name,Values=running" 
  --query "Reservations[*].Instances[*].{InstanceId:InstanceId,PublicIp:PublicIpAddress}" 
  --output table

Filters to running instances only, then uses JMESPath to project a concise table of instance IDs and public IPs. Ideal for quick inventory checks across an account.

Example 2: Retrieve tags from a specific instance

aws ec2 describe-instances 
  --instance-ids i-0abcd1234efgh5678 
  --query "Reservations[*].Instances[*].Tags" 
  --output json

Returns the full tag array for one instance. Use with jq to extract specific keys: aws ec2 describe-instances --instance-ids i-... --query "Reservations[*].Instances[*].Tags" | jq '.[][][] | select(.Key=="Name") | .Value'.

Example 3: Complex multi-filter with JSON file

# filters.json
# [
#   {"Name": "instance-type", "Values": ["t2.micro","t3.micro"]},
#   {"Name": "availability-zone", "Values": ["us-east-2c"]}
# ]
aws ec2 describe-instances 
  --filters file://filters.json 
  --query "Reservations[*].Instances[*].{InstanceId:InstanceId,Type:InstanceType,AZ:Placement.AvailabilityZone}" 
  --output table

For complex filter sets, store in a JSON file to avoid shell escaping issues. This example retrieves only t2.micro and t3.micro instances in us-east-2c and displays a custom table.

Example 4: Paginate through 5000+ instances

aws ec2 describe-instances 
  --max-items 1000 
  --page-size 200 
  --query "Reservations[*].Instances[*].InstanceId" 
  --output text

Use --max-items to control total results (1000 per call) and --page-size to reduce API throttling (200 per page). The CLI automatically handles the next token. To get all results, avoid --max-items unless you want to stop early.

Troubleshooting & Common Errors

Exit Codes

Closing Tip

Always pair --query with --output text in shell loops and scripts to avoid JSON parsing overhead, for example: for id in $(aws ec2 describe-instances --query "Reservations[*].Instances[*].[InstanceId]" --output text); do echo "$id"; done.

Multi-Cloud Comparison

aws ec2 describe-instances --filters "Name=instance-state-name,Values=running"

aws ec2 describe-instances --query 'Reservations[].Instances[?State.Name==`running`]'

aws ec2 describe-instances --query 'Reservations[*].Instances[*].[InstanceId,State.Name]' --output table

aws ec2 describe-instances --output json | jq '.Reservations[].Instances[] | {id: .InstanceId, state: .State.Name}'

{
  "Effect": "Allow",
  "Action": "ec2:DescribeInstances",
  "Resource": "*"
}

aws sts get-caller-identity

az vm list --output table

gcloud compute instances list --format="table(name,zone,status)"

aws ec2 describe-instances 
  --filters "Name=instance-state-name,Values=running" 
  --query 'Reservations[*].Instances[*].[Tags[?Key==`Name`].Value|[0],InstanceId]' 
  --output text