AWS Documentation » Amazon EC2 » Command Line Reference » Commands (CLI Tools) » ec2-describe-instances	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

ec2-describe-instances

Description

Describes one or more of your instances.

If you specify one or more instance IDs, Amazon EC2 returns information for those instances. If you do not specify instance IDs, Amazon EC2 returns information for all relevant instances. If you specify an invalid instance ID, an error is returned. If you specify an instance that you do not own, it will not be included in the returned results.

Recently terminated instances might appear in the returned results. This interval is usually less than one hour.

The short version of this command is ec2din.

Syntax

ec2-describe-instances [instance_id ...] [[--filter "name=value"] ...]

Options

Name Description

Name	Description
`instance_id`	One or more instance IDs. Type: String Default: Describes all your instances. Required: No Example: i-15a4417c
`-F, --filter` `name`=`value`	A filter for limiting the results. See the Supported Filters section for a list of supported filters. Use quotation marks if the value string has a space ("name=value example"). On a Windows system, use quotation marks even without a space in the value string ("name=value"). Type: String Default: Describes all your instances, or only those you specified by ID. Required: No Example: --filter "tag-key=Production"

instance_id

One or more instance IDs.

Type: String

Default: Describes all your instances.

Required: No

Example: i-15a4417c

-F, --filter name=value

A filter for limiting the results. See the Supported Filters section for a list of supported filters. Use quotation marks if the value string has a space ("name=value example"). On a Windows system, use quotation marks even without a space in the value string ("name=value").

Type: String

Default: Describes all your instances, or only those you specified by ID.

Required: No

Example: --filter "tag-key=Production"

Supported Filters

You can specify filters so that the response includes information for only certain instances. For example, you can use a filter to specify that you're interested in instances launched with a specific key pair. You can specify multiple values for a filter. The response includes information for an instance only if it matches at least one of the filter values that you specified.

You can specify multiple filters; for example, specify instances that are launched with a specific key pair and use an Amazon EBS volume as the root device. The response includes information for an instance only if it matches all the filters that you specified. If there's no match, no special message is returned, the response is simply empty.

You can use wildcards in a filter value. An asterisk (*) matches zero or more characters, and a question mark (?) matches exactly one character. You can escape special characters using a backslash (\) before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\.

The following are the available filters.

architecture

The instance architecture.

Type: String

Valid values: i386 | x86_64

availability-zone

The Availability Zone of the instance.

Type: String

block-device-mapping.attach-time

The attach time for an Amazon EBS volume mapped to the instance (for example, 2010-09-15T17:15:20.000Z)

Type: DateTime

block-device-mapping.delete-on-termination

Indicates whether the Amazon EBS volume is deleted on instance termination.

Type: Boolean

block-device-mapping.device-name

The device name (for example, /dev/sdh) for the Amazon EBS volume.

Type: String

block-device-mapping.status

The status for the Amazon EBS volume.

Type: String

Valid values: attaching | attached | detaching | detached

block-device-mapping.volume-id

The volume ID of the Amazon EBS volume.

Type: String

client-token

The idempotency token you provided when you launched the instance.

Type: String

dns-name

The public DNS name of the instance.

Type: String

group-id

The ID of the security group for the instance. If the instance is in a VPC, use instance.group-id instead.

Type: String

group-name

The name of the security group for the instance. If the instance is in a VPC, use instance.group-name instead.

Type: String

image-id

The ID of the image used to launch the instance.

Type: String

instance-id

The ID of the instance.

Type: String

instance-lifecycle

Indicates whether this is a Spot Instance.

Type: String

Valid values: spot

instance-state-code

The state of the instance. The high byte is an opaque internal value and should be ignored. The low byte is set based on the state represented.

Type: Integer (16-bit unsigned integer)

instance-state-name

The state of the instance.

Type: String

instance-type

The type of instance (for example, m1.small).

Type: String

instance.group-id

The ID of the security group for the instance. If the instance is in a VPC, use group-id instead.

Type: String

instance.group-name

The name of the security group for the instance. if the instance is in a VPC, use group-name instead.

Type: String

ip-address

The public IP address of the instance.

Type: String

kernel-id

The kernel ID.

Type: String

key-name

The name of the key pair used when the instance was launched.

Type: String

launch-index

When launching multiple instances, this is the index for the instance in the launch group (for example, 0, 1, 2, and so on).

Type: String

launch-time

The time the instance was launched (for example, 2010-08-07T11:54:42.000Z).

Type: DateTime

monitoring-state

Indicates whether monitoring is enabled for the instance.

Type: String

Valid values: disabled | enabled

owner-id

The AWS account ID of the instance owner.

Type: String

placement-group-name

The name of the placement group for the instance.

Type: String

platform

The platform. Use windows if you have Windows based instances; otherwise, leave blank.

Type: String

Valid value: windows

private-dns-name

The private DNS name of the instance.

Type: String

private-ip-address

The private IP address of the instance.

Type: String

product-code

The product code associated with the AMI used to launch the instance.

Type: String

product-code.type

The type of product code.

Type: String

Valid values: devpay | marketplace

ramdisk-id

The RAM disk ID.

Type: String

reason

The reason for the current state of the instance (for example, shows "User Initiated [date]" when you stop or terminate the instance). Similar to the state-reason-code filter.

Type: String

requester-id

The ID of the entity that launched the instance on your behalf (for example, AWS Management Console, Auto Scaling, and so on)

Type: String

reservation-id

The ID of the instance's reservation. A reservation ID is created any time you launch an instance. A reservation ID has a one-to-one relationship with an instance launch request, but can be associated with more than one instance if you launch multiple instances using the same launch request. For example, if you launch one instance, you'll get one reservation ID. If you launch ten instances using the same launch request, you'll also get one reservation ID.

Type: String

root-device-name

The name of the root device for the instance (for example, /dev/sda1).

Type: String

root-device-type

The type of root device the instance uses.

Type: String

Valid values: ebs | instance-store

source-dest-check

Indicates whether the instance performs source/destination checking. A value of true means that checking is enabled, and false means checking is disabled. The value must be false for the instance to perform network address translation (NAT) in your VPC.

Type: Boolean

spot-instance-request-id

The ID of the Spot Instance request.

Type: String

state-reason-code

The reason code for the state change.

Type: String

state-reason-message

A message that describes the state change.

Type: String

subnet-id

The ID of the subnet for the instance.

Type: String

tag-key

The key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter "tag-key=Purpose" and the filter "tag-value=X", you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose is X, see the tag:key filter.

For more information about tags, see Tagging Your Resources in the Amazon Elastic Compute Cloud User Guide.

Type: String

tag-value

The value of a tag assigned to the resource. This filter is independent of the tag-key filter.

Type: String

tag:key

Filters the response based on a specific tag/value combination.

Example: To list just the resources that have been assigned tag Purpose=X, specify:

--filter tag:Purpose=X

Example: To list just resources that have been assigned tag Purpose=X OR Purpose=Y, specify:

--filter tag:Purpose=X --filter tag:Purpose=Y

virtualization-type

The virtualization type of the instance.

Type: String

Valid values: paravirtual | hvm

vpc-id

The ID of the VPC the instance is running in.

Type: String

hypervisor

The hypervisor type of the instance.

Type: String

Valid values: ovm | xen

network-interface.description

The description of the network interface.

Type: String

network-interface.subnet-id

The ID of the subnet for the network interface.

Type: String

network-interface.vpc-id

The ID of the VPC for the network interface.

Type: String

network-interface.network-interface.id

The ID of the network interface.

Type: String

network-interface.owner-id

The ID of the owner of the network interface.

Type: String

network-interface.availability-zone

The availability zone for the network interface.

Type: String

network-interface.requester-id

The requester ID for the network interface.

Type: String

network-interface.requester-managed

Indicates whether the network interface is being managed by AWS.

Type: Boolean

network-interface.status

The status of the network interface.

Type: String

Valid values: available | in-use

network-interface.mac-address

The MAC address of the network interface.

Type: String

Valid values: available | in-use

network-interface-private-dns-name

The private DNS name of the network interface.

Type: String

network-interface.source-destination-check

Whether the network interface performs source/destination checking. A value of true means checking is enabled, and false means checking is disabled. The value must be false for the network interface to perform network address translation (NAT) in your VPC.

Type: Boolean

network-interface.group-id

The ID of a security group associated with the network interface.

Type: String

network-interface.group-name

The name of a security group associated with the network interface.

Type: String

network-interface.attachment.attachment-id

The ID of the interface attachment.

Type: String

network-interface.attachment.instance-id

The ID of the instance to which the network interface is attached.

Type: String

network-interface.attachment.instance-owner-id

The owner ID of the instance to which the network interface is attached.

Type: String

network-interface.addresses.private-ip-address

The private IP address associated with the network interface.

Type: String

network-interface.attachment.device-index

The device index to which the network interface is attached.

Type: Integer

network-interface.attachment.status

The status of the attachment.

Type: String

Valid values: attaching | attached | detaching | detached

network-interface.attachment.attach-time

The time that the network interface was attached to an instance.

Type: Date

network-interface.attachment.delete-on-termination

Specifies whether the attachment is deleted when an instance is terminated.

Type: Boolean

network-interface.addresses.primary

Specifies whether the IP address of the network interface is the primary private IP address.

Type: Boolean

network-interface.addresses.association.public-ip

The ID of the association of an Elastic IP address with a network interface.

Type: String

network-interface.addresses.association.ip-owner-id

The owner ID of the private IP address associated with the network interface.

Type: String

association.public-ip

The address of the Elastic IP address bound to the network interface.

Type: String

association.ip-owner-id

The owner of the Elastic IP address associated with the network interface.

Type: String

association.allocation-id

The allocation ID that AWS returned when you allocated the Elastic IP address for your network interface.

Type: String

association.association-id

The association ID returned when the network interface was associated with an IP address.

Type: String

Common Options

Option	Description
`--region` `REGION`	Overrides the region specified by the `EC2_URL` environment variable and the URL specified by the `-U` option. Default: The value of the `EC2_URL` environment variable, or `us-east-1` if `EC2_URL` isn't set. Example: `--region eu-west-1`
`-U, --url` `URL`	The uniform resource locator (URL) of the Amazon EC2 web service entry point. Default: The value of the `EC2_URL` environment variable, or https://ec2.amazonaws.com if `EC2_URL` isn't set. Example: `-U https://ec2.amazonaws.com`
`-K, --private-key` `EC2-PRIVATE-KEY`	The private key that identifies you to Amazon EC2. For more information, see Tell the Tools Who You Are. Default: The value of the `EC2_PRIVATE_KEY` environment variable. If `EC2_PRIVATE_KEY` isn't set, you must specify this option. Example: `-K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`
`-C, --cert` `EC2-CERT`	The X.509 certificate that identifies you to Amazon EC2. Default: The value of the `EC2_CERT` environment variable. If `EC2_CERT` isn't set, you must specify this option. Example: `-C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`
`-O, --aws-access-key` `AWS_ACCESS_KEY`	The access key ID associated with your AWS account. For more information, see Tell the Tools Who You Are. Default: The value of the `AWS_ACCESS_KEY` environment variable. If `AWS_ACCESS_KEY` isn't set, you must specify this option. Example: `-O AKIAIOSFODNN7EXAMPLE` Note For more information, see the following section, Deprecated Options.
`-W, --aws-secret-key` `AWS_SECRET_KEY`	The secret access key associated with your AWS account. Default: The value of the `AWS_SECRET_KEY` environment variable. If `AWS_SECRET_KEY` isn't set, you must specify this option. Example: `-W wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` Note For more information, see the following section, Deprecated Options.
`-T, --security-token TOKEN` `AWS_DELEGATION_TOKEN`	The AWS delegation token. Default: The value of the environment variable (if set).
`--connection-timeout` `TIMEOUT`	The connection timeout, in seconds. Example: `--connection-timeout 30`
`--request-timeout` `TIMEOUT`	The request timeout, in seconds. Example: `--request-timeout 45`
`-v, --verbose`	Displays verbose output, including the API request and response on the command line. This is useful if you are building tools to talk directly to our Query API.
`-H, --headers`	Includes column headers in the command output.
`--show-empty-fields`	Shows empty columns as `(nil)`.
`--hide-tags`	Omits tags for tagged resources.
`--debug`	Displays internal debugging information. This can assist us when helping you troubleshooting problems.
`-?, --help, -h`	Displays usage information for the command.
`-`	Reads arguments from standard input. This is useful when piping the output from one command to the input of another. Example: `ec2-describe-instances \| grep stopped \| cut -f 2 \| ec2-start-instances -`

Deprecated Options

For a limited time, you can still use the private key and X.509 certificate instead of your access key ID and secret access key. However, we recommend that you start using your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) now, as the private key (-K, --private-key) and X.509 certificate (-C, --cert) won't be supported after the transition period elapses. For more information, see Tell the Tools Who You Are.

Option Description

Option	Description
`-K, --private-key` `EC2-PRIVATE-KEY`	The private key to use when constructing requests to Amazon EC2. Default: The value of the `EC2_PRIVATE_KEY` environment variable. Example: `-K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`
`-C, --cert` `EC2-CERT`	The X.509 certificate to use when constructing requests to Amazon EC2. Default: The value of the `EC2_CERT` environment variable. Example: `-C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`

-K, --private-key EC2-PRIVATE-KEY

The private key to use when constructing requests to Amazon EC2.

Default: The value of the EC2_PRIVATE_KEY environment variable.

Example: -K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

-C, --cert EC2-CERT

The X.509 certificate to use when constructing requests to Amazon EC2.

Default: The value of the EC2_CERT environment variable.

Example: -C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem

Output

This command returns a table that contains the following rows of information for each instance. Each field is separated by a comma. Some of these values may be empty.

The reservation information
- The RESERVATION identifier
- The ID of the reservation
- The AWS account ID of the instance owner
- The name of each security group the instance is in
The instance information
- The INSTANCE identifier
- The ID of the instance
- The AMI ID of the image on which the instance is based
- The public DNS name associated with the instance. This is only present for instances in the running state.
- The private DNS name associated with the instance. This is only present for instances in the running state.
- The state of the instance
- The key name. If a key was associated with the instance at launch, its name will appear.
- The AMI launch index
- The product codes associated with the instance
- The instance type
- The instance launch time
- The Availability Zone
- The ID of the kernel
- The ID of the RAM disk
- The platform (windows or empty)
- The monitoring state
- The public IP address
- The private IP address
- [EC2-VPC] The ID of the VPC
- [EC2-VPC] The subnet ID
- The type of root device (ebs or instance-store)
- The instance lifecycle
- The Spot Instance request ID
- The instance license
- The placement group the cluster instance is in
- The virtualization type (paravirtual or hvm)
- The hypervisor type (xen or ovm)
- The client token
- The ID of each security group the instance is in
- The tenancy of the instance (default or dedicated)
- Whether or not the instance is EBS optimized (true or false)
- The Amazon Resource Name (ARN) of the IAM role
Any EBS volumes associated with the instance. There will be one of the following for each volume
- The BLOCKDEVICE identifier
- The device name
- The volume ID
- The volume attach timestamp
- Whether or not the volume will be deleted on termination (true or false)
- The volume type
- The I/O operations per second (IOPS)
[EC2-VPC] The network interface information. There will be a set of the following for each network interface
1. The network interface information
  - The NIC identifier
  - The network interface ID
  - The subnet ID
  - The VPC ID
  - The owner ID
  - The network interface status
  - The private IP address of the network interface
  - The private DNS name
  - Whether or not source destination check is enabled (true or false)
2. The network interface attachment information
  - The NICATTACHMENT identifier
  - The attachment ID
  - The device index
  - The device status
  - The attachment timestamp
  - Whether or not the attachment is deleted on termination (true or false)
3. The network interface association information
  - The NICASSOCIATION identifier
  - The public IP address
  - The public IP address owner
  - The private IP address
4. The security group information
  - The GROUP identifier
  - The security group identifier
  - The security group name
5. The private IP address information
  - The PRIVATEIPADDRESS identifier
  - The private IP address
Any tags associated with the instance. There will be one of the following for each tag
- The TAG identifier
- The resource type identifier
- The resource ID
- The tag key
- The tag value

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example describes the current state of the instances owned by your AWS account.

PROMPT> ec2-describe-instances

RESERVATION	r-1a2b3c4d	111122223333	my-security-group
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d	ec2-67-202-51-223.compute-1.amazonaws.com	ip-10-251-50-35.ec2.internal	running	gsg-keypair	0		t1.micro	YYYY-MM-DDTHH:MM:SS+0000	us-west-2a	aki-1a2b3c4d			monitoring-disabled	184.73.10.99	10.254.170.223			ebs					paravirtual	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sda1       vol-1a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
BLOCKDEVICE     /dev/sdb        vol-2a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
TAG	instance	i-1a2b3c4d	Name	Linux
RESERVATION     r-2a2b3c4d      111122223333    another-security-group
INSTANCE	i-2a2b3c4d	ami-2a2b3c4d	ec2-67-202-51-223.compute-1.amazonaws.com	ip-10-251-50-35.ec2.internal	running	gsg-keypair	0		t1.micro	YYYY-MM-DDTHH:MM:SS+0000	us-west-2c			windows	monitoring-disabled	50.112.203.9	10.244.168.218			ebs					hvm	xen	ABCDE1234567890123	sg-2a2b3c4d	default	false	
TAG	instance	i-2a2b3c4d	Name	Windows

Example Request

This example filters the response to include only the m1.small or m1.large instances that have an Amazon EBS volume that is both attached and set to delete on termination.

PROMPT> ec2-describe-instances --filter "instance-type=m1.small" --filter "instance-type=m1.large" --filter "block-device-mapping.status=attached" --filter "block-device-mapping.delete-on-termination=true"
RESERVATION	r-1a2b3c4d	111122223333	my-security-group
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d	ec2-67-202-51-223.compute-1.amazonaws.com	ip-10-251-50-35.ec2.internal	running	gsg-keypair	0		t1.micro	YYYY-MM-DDTHH:MM:SS+0000	us-west-2a	aki-1a2b3c4d			monitoring-disabled	184.73.10.99	10.254.170.223			ebs					paravirtual	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sdb        vol-1a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
TAG	instance	i-1a2b3c4d	Name	Linux

Example Request

This example describes all instances that are running in a VPC.

PROMPT> ec2-describe-instances --filter "vpc-id=*" 
RESERVATION	r-1a2b3c4d	111122223333		
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d			running	gsg-keypair	0		m1.small	YYYY-MM-DDTHH:MM:SS+0000	us-west-2b			windows	monitoring-disabled	50.112.172.209	10.0.0.167	vpc-1a2b3c4d	subnet-1a2b3c4d	ebs					hvm	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sdb        vol-1a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
NIC	eni-1a2b3c4d	subnet-1a2b3c4d	vpc-1a2b3c4d	111122223333	in-use	10.0.1.167		true
NICATTACHMENT	eni-attach-1a2b3c4d	0	attached	YYYY-MM-DDTHH:MM:SS+0000	true
GROUP	sg-1a2b3c4d	my-security-group
PRIVATEIPADDRESS	10.0.1.167
PRIVATEIPADDRESS	10.0.1.12
TAG	instance	i-1a2b3c4d	Name	Windows
RESERVATION	r-2a2b3c4d	111122223333		
INSTANCE	i-2a2b3c4d	ami-2a2b3c4d			running	gsg-keypair	0		c1.medium	YYYY-MM-DDTHH:MM:SS+0000	us-west-2b	aki-1a2b3c4d			monitoring-disabled	50.112.172.209	10.0.0.233	vpc-1a2b3c4d	subnet-1a2b3c4d	ebs					hvm	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sda1       vol-2a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
NIC	eni-2a2b3c4d	subnet-1a2b3c4d	vpc-1a2b3c4d	111122223333	in-use	10.0.1.233		true
NICATTACHMENT	eni-attach-2a2b3c4d	0	attached	YYYY-MM-DDTHH:MM:SS+0000	true
GROUP	sg-1a2b3c4d	my-security-group
PRIVATEIPADDRESS	10.0.1.233
PRIVATEIPADDRESS	10.0.1.20
TAG	instance	i-1a2b3c4d	Name	Linux

Example Request

This example describes any instances with a network interface that have a private IP address of 10.0.0.120.

PROMPT> ec2-describe-instances --filter "network-interface.addresses.private-ip-address=10.0.0.120" 
RESERVATION	r-1a2b3c4d	111122223333 
INSTANCE	i-1a2b3c4d	ami-1a2b3c4d			running	gsg-keypair	0		c1.medium	YYYY-MM-DDTHH:MM:SS+0000	us-west-2b	aki-1a2b3c4d			monitoring-disabled	50.112.172.209	10.0.0.98	vpc-1a2b3c4d	subnet-1a2b3c4d	ebs					hvm	xen	ABCDE1234567890123	sg-1a2b3c4d	default	false	
BLOCKDEVICE     /dev/sdb        vol-1a2b3c4d    YYYY-MM-DDTHH:MM:SS.SSSZ	true	
NIC	eni-1a2b3c4d	subnet-1a2b3c4d	vpc-1a2b3c4d	111122223333	in-use	10.0.1.98		true
NICATTACHMENT	eni-attach-1a2b3c4d	0	attached	YYYY-MM-DDTHH:MM:SS+0000	true
GROUP	sg-1a2b3c4d	my-security-group
PRIVATEIPADDRESS	10.0.0.98 
PRIVATEIPADDRESS	10.0.0.120

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...

ec2-describe-instances

Description

Syntax

Options

Supported Filters

Common Options

Deprecated Options

Output

Examples

Example Request

Example Request

Example Request

Example Request

Related Topics

Download

Related Action

ec2-describe-instances

Description

Syntax

Options

Supported Filters

Common Options

Deprecated Options

Output

Examples

Example Request

Example Request

Example Request

Example Request

Related Topics

Download

Related Action

Related Commands