ec2-describe-images

Description

Returns information about AMIs, AKIs, and ARIs. Images available to you include public images, private images that you own, and private images owned by other AWS accounts but for which you have explicit launch permissions.

Launch permissions fall into three categories:

Launch Permission	Description
public	The owner of the AMI granted launch permissions for the AMI to the `all` group. All AWS accounts have launch permissions for these AMIs.
explicit	The owner of the AMI granted launch permissions to a specific AWS account.
implicit	An AWS account has implicit launch permissions for all the AMIs it owns.

The list of AMIs returned can be modified by specifying AMI IDs, AMI owners, or AWS accounts with launch permissions. If no options are specified, Amazon EC2 returns all AMIs for which you have launch permissions.

If you specify one or more AMI IDs, only AMIs that have the specified IDs are returned. If you specify an invalid AMI ID, an error is returned. If you specify an AMI ID for which you do not have access, it will not be included in the returned results.

If you specify one or more AMI owners, only AMIs from the specified owners and for which you have access are returned. The results can include the account IDs of the specified owners, amazon for AMIs owned by Amazon, or self for AMIs that you own.

If you specify a list of executable users, only AMIs with launch permissions for those users are returned. You can specify account IDs (if you own the AMI(s)), self for AMIs for which you own or have explicit permissions, or all for public AMIs.

	Note
	Deregistered images are included in the returned results for an unspecified interval after deregistration.

You can filter the results to return information only about images that match criteria you specify. For example, you could get information only about images that use a certain kernel. You can specify multiple values for a filter (e.g., the image uses either kernel aki-1a2b3c4d or kernel aki-9b8c7d6f). An image must match at least one of the specified values for it to be included in the results.

You can specify multiple filters (e.g., the image uses a certain kernel, and uses an Amazon EBS volume as the root device). The result includes information for a particular image only if it matches all your filters. If there's no match, no special message is returned; the response is simply empty.

You can use wildcards with the filter values: * matches zero or more characters, and ? 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 table shows the available filters.

Filter Name	Description
`architecture`	Image architecture. Type: String Valid Values: `i386` \| `x86_64`
`block-device-mapping.delete-on-termination`	Whether the Amazon EBS volume is deleted on instance termination. Type: Boolean
`block-device-mapping.device-name`	Device name (e.g., /dev/sdh) for an Amazon EBS volume mapped to the image. Type: String
`block-device-mapping.snapshot-id`	Snapshot ID for an Amazon EBS volume mapped to the image. Type: String
`block-device-mapping.volume-size`	Volume size for an Amazon EBS volume mapped to the image. Type: Integer
`description`	Description of the AMI (provided during image creation). Type: String
`image-id`	ID of the image. Type: String
`image-type`	Type of image. Type: String Valid Values: `machine` \| `kernel` \| `ramdisk`
`is-public`	Whether the image is public. Type: Boolean
`kernel-id`	Kernel ID. Type: String
`manifest-location`	Location of the image manifest. Type: String
`name`	Name of the AMI (provided during image creation). Type: String
`owner-alias`	AWS account alias (e.g., `amazon`) Type: String
`owner-id`	AWS account ID of the image owner. Type: String
`platform`	Use `windows` if you have Windows based AMIs; otherwise leave blank. Type: String Valid Value: `windows`
`product-code`	Product code associated with the AMI. Type: String
`ramdisk-id`	RAM disk ID. Type: String
`root-device-name`	Root device name of the AMI (e.g., /dev/sda1). Type: String
`root-device-type`	Root device type the AMI uses. Type: String Valid Values: `ebs` \| `instance-store`
`state`	State of the image. Type: String Valid Values: `available` \| `pending` \| `failed`
`state-reason-code`	Reason code for the state change. Type: String
`state-reason-message`	Message for the state change. Type: String
`tag-key`	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=X, see the `tag:key` filter later in this table. For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String
`tag-value`	Value of a tag assigned to the resource. This filter is independent of the `tag-key` filter. Type: String
`tag:``key`	Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify: `--filter tag:Purpose=X` Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify: `--filter tag:Purpose=X --filter tag:Purpose=Y`
`virtualization-type`	Virtualization type of the image. Type: String Valid Values: `paravirtual` \| `hvm`
`hypervisor`	Hypervisor type of the image. Type: String Valid Values: `ovm` \| `xen`

The short version of this command is ec2dim.

Syntax

ec2-describe-images [ami_id ...] [-a] [-o owner ...] [-x user_id ...] [[--filter name=value] ...]

Options

Name	Description	Required
`ami_id`	AMI IDs to describe. Type: String Default: Returns all AMIs. Example: ami-78a54011	No
`-a, --all`	Describes all AMIs. Type: String Default: None Example: -a	No
`-o, --owner` `owner`	Returns AMIs owned by the specified owner. Multiple owner options can be specified. The IDs `amazon` and `self` can be used to include AMIs owned by Amazon or AMIs owned by you, respectively. Type: String Default: None Valid Values: `amazon` \| `self` \| AWS account ID Example: -o self	No
`-x, --executable-by` `user_id`	Returns AMIs for which the specified user ID has explicit launch permissions. The user ID can be an AWS account ID, `self` to return AMIs for which the sender of the request has explicit launch permissions, or `all` to return AMIs with public launch permissions. Type: String Default: None Valid Values: `all` \| `self` \| AWS account ID Example: -x self	No
`--filter` `name`=`value`	A filter for limiting the results. See the preceding table for a list of allowed filter names and values. If you're using the command line tools on a Windows system, you might need to use quotation marks (i.e., "name=value"). Type: String Default: None Example: --filter "tag-value=Production"	No

Common Options

Option	Description
`--region` `REGION`	Overrides the Region specified in the `EC2_URL` environment variable and the URL specified by the `-U` option. Default: The `EC2_URL` environment variable, or `us-east-1` if the environment variable is not set. Example: `--region eu-west-1`
`-U, --url` `URL`	`URL` is the uniform resource locator of the Amazon EC2 web service entry point. Default: The `EC2_URL` environment variable, or https://ec2.amazonaws.com if the environment variable is not set. Example: `-U https://ec2.amazonaws.com`
`-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-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.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-HKZYKTAIG2ECMXYIBH3HXV4ZBZQ55CLO.pem`
`--connection-timeout` `TIMEOUT`	Specifies a connection timeout (in seconds). Example: --connection-timeout 30
`--request-timeout` `TIMEOUT`	Specifies a request timeout (in seconds). Example: --request-timeout 45
`-v, --verbose`	Displays verbose output by showing the SOAP request and response on the command line. This is particularly useful if you are building tools to talk directly to our SOAP API.
`-H, --headers`	Displays column headers in the output.
`--show-empty-fields`	Shows empty columns as `(nil)`.
`--hide-tags`	Do not display tags for tagged resources.
`--debug`	Prints internal debugging information. This is useful to assist us when troubleshooting problems.
`-?, --help, -h`	Displays Help.
`-`	If `-` is specified as an argument to one of the parameters, a list of arguments is read from standard input. This is useful for piping the output of one command into the input of another. Example: `ec2-describe-instances \| grep stopped \| cut -f 2 \| ec2-start-instances -`

Output

The command returns a table that contains the following information:

IMAGE identifier
Image ID
Manifest location
ID of the AWS account that registered the image (or "amazon")
Image status (available, pending, failed)
Image visibility (public or private)
Product codes, if any, that are attached to the instance
Image architecture (i386 or x86_64)
Image type (machine, kernel, or ramdisk)
ID of the kernel associated with the image (machine images only)
ID of the RAM disk associated with the image (machine images only)
Type of root device (ebs or instance-store)
Virtualization type (paravirtual or hvm)
BLOCKDEVICEMAPPING identifier for AMIs that use one or more Amazon EBS volumes
Any tags assigned to the image
Hypervisor type (xen or ovm)

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example describes the ami-be3adfd7 AMI.

PROMPT> ec2-describe-images ami-be3adfd7
IMAGE ami-78a54011 amazon/getting-started-with-ebs-boot amazon available 
public  i386 machine aki-a13667e4 ari-a33667e6 ebs paravirtual xen
BLOCKDEVICEMAPPING /dev/sda1 snap-8eaf78e6 15

Example Request

This example filters the results to display only the public Windows images with an x86_64 architecture.

PROMPT> ec2-describe-images --filter "is-public=true" --filter "architecture=x86_64" --filter "platform=windows"
IMAGE   ami-dd20c3b4    ec2-public-windows-images/Server2003r2-x86_64-Win-v1.07.manifest.xml    amazon  available       public          x86_64  machine          windows instance-store  hvm  xen
IMAGE   ami-0535d66c    ec2-public-windows-images/SqlSvrStd2003r2-x86_64-Win-v1.07.manifest.xml amazon  available       public          x86_64  machine          windows instance-store  hvm  xen
...

Description

Syntax

Options

Common Options

Output

Examples

Example Request

Example Request

Related Operations