Amazon Elastic Compute Cloud
CLI Reference (API Version 2014-10-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.

ec2-describe-images

Description

Describes one or more of the images (AMIs, AKIs, and ARIs) available to you. 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 PermissionDescription
publicThe owner of the image granted launch permissions for the image to the all group. All AWS accounts have launch permissions for these images.
explicitThe owner of the image granted launch permissions to a specific AWS account.
implicitAn AWS account has implicit launch permissions for all the images it owns.

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

If you specify one or more image IDs, only images that have the specified IDs are returned. If you specify an image to which you don't have access, it's not included in the returned results.

If you specify one or more owners, only images from the specified owners and to which you have access are returned. The results can include the account IDs of the specified owners—amazon for images owned by Amazon, aws-marketplace for images owned by AWS Marketplace, or self for images that you own.

Note

For an overview of the AWS Marketplace, see Introducing AWS Marketplace.

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

Note

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

The short version of this command is ec2dim.

Tip

If you are using the AWS CLI, see describe-images instead.

Syntax

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

Options

NameDescription

ami_id

One or more image IDs.

Type: String

Default: Describes all images available to you.

Required: No

Example: ami-78a54011

-a, --all

Describes all images available to you.

Type: String

Default: None

Required: No

Example: -a

-o, --owner owner

Describes images owned by the specified owners. Use the IDs amazon, aws-marketplace, and self to describe images owned by Amazon, AWS Marketplace, or you, respectively.

Type: String

Valid values: amazon | aws-marketplace | self | AWS account ID | all

Default: None

Required: No

Example: -o self

-x, --executable-by user_id

Describes images for which the specified user has explicit launch permissions. The user can be an AWS account ID, self to return images for which the sender of the request has explicit launch permissions, or all to return images with public launch permissions.

Type: String

Valid values: all | self | AWS account ID

Default: None

Required: No

Example: -x self

-F, --filter name=value

A filter for limiting the results. For more information, see the Supported Filters section. Filter names and values are case-sensitive. 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=valueexample"). If you are using Windows Powershell, you might need to use a second set of quotation marks, escaped with backticks ("`"name=valueexample`"").

Type: String

Default: Describes all images available to you, or only those you specified.

Required: No

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

Supported Filters

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

You can specify multiple filters; for example, specify images that use a specific kernel and use an Amazon EBS volume as the root device. The response includes information for an image 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 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

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

Type: String

block-device-mapping.snapshot-id

The ID of the snapshot used for the Amazon EBS volume.

Type: String

block-device-mapping.volume-size

The volume size of the Amazon EBS volume, in GiB.

Type: Integer

block-device-mapping.volume-type

The volume type of the Amazon EBS volume.

Type: String

Valid values: gp2 for General Purpose (SSD) volumes, io1 for Provisioned IOPS (SSD) volumes, and standard for Magnetic volumes.

description

The description of the image (provided during image creation).

Type: String

image-id

The ID of the image.

Type: String

image-type

The image type.

Type: String

Valid values: machine | kernel | ramdisk

is-public

Whether the image is public.

Type: Boolean

kernel-id

The kernel ID.

Type: String

manifest-location

The location of the image manifest.

Type: String

name

The name of the AMI (provided during image creation).

Type: String

owner-alias

The AWS account alias (for example, amazon).

Type: String

owner-id

The AWS account ID of the image owner.

Type: String

platform

The platform. To only list Windows-based AMIs, use windows.

Type: String

Valid value: windows

product-code

The product code.

Type: String

product-code.type

The type of the product code.

Type: String

Valid values: devpay | marketplace

ramdisk-id

The RAM disk ID.

Type: String

root-device-name

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

Type: String

root-device-type

The type of the root device volume.

Type: String

Valid values: ebs | instance-store

state

The state of the image.

Type: String

Valid values: available | pending | failed

state-reason-code

The reason code for the state change.

Type: String

state-reason-message

The message for the state change.

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=value filter.

For more information about tags, see Tagging Your Resources in the Amazon EC2 User Guide for Linux Instances.

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=value

The key/value combination of a tag assigned to the resource.

Example: To list the resources with the tag Purpose=X, use:

--filter tag:Purpose=X

Example: To list resources with the tag Purpose=X or the tag Purpose=Y, use:

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

virtualization-type

The virtualization type.

Type: String

Valid values: paravirtual | hvm

hypervisor

The hypervisor type.

Type: String

Valid values: ovm | xen

Common Options

OptionDescription

--region region

The region. Overrides the default region, the region specified by the EC2_URL environment variable, and the URL specified by the -U option.

Default: The region specified by the EC2_URL environment variable, or us-east-1 if EC2_URL isn't set.

-U, --url url

The uniform resource locator (URL) of the Amazon EC2 web service entry point.

Default: The endpoint specified by the EC2_URL environment variable, or https://ec2.amazonaws.com if EC2_URL isn't set.

-O, --aws-access-key aws_access_key_id

Your access key ID. 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

-W, --aws-secret-key aws_secret_access_key

Your secret access key.

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

-T, --security-token delegation_token

The delegation token to pass along to the AWS request. This is only required when you are using temporary security credentials. For more information, see Using Temporary Security Credentials.

Default: The value of the AWS_DELEGATION_TOKEN environment variable (if set).

Example: -t AQoDYXdzEJr...<remainder of security token>

--connection-timeout timeout

The connection timeout, in seconds.

Example: --connection-timeout 30

--request-timeout timeout

The request timeout, in seconds.

Example: --request-timeout 45

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

-D, --auth-dry-run

Checks whether you have the required permissions for the command, without actually running the command. If you have the required permissions, the command returns DryRunOperation; otherwise, it returns UnauthorizedOperation.

-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 the Query API.

-

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 -

-?, --help, -h

Displays usage information for the command.

Deprecated Options

We have deprecated the SOAP API for Amazon EC2. For more information, see SOAP Requests. From version 1.6.14.0 onwards of the Amazon EC2 CLI tools, the private key (-K, --private-key) and X.509 certificate (-C, --cert) options are not supported. Use your access key ID (-O, --aws-access-key) and secret access key (-W, --aws-secret-key) instead. For more information, see Setting Up the Amazon EC2 CLI and AMI Tools.

OptionDescription

-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 image. Some fields may be empty.

  1. The image information

    • The IMAGE identifier

    • The ID of the image

    • The source of the image

    • The ID of the image owner

    • The status of the image

    • The visibility of the image (public or private)

    • The product codes, if any, that are attached to the instance

    • The architecture of the image (i386 or x86_64)

    • The image type (machine, kernel, or ramdisk)

    • The ID of the kernel associated with the image (machine images only)

    • The ID of the RAM disk associated with the image (machine images only)

    • The platform of the image

    • The type of root device (ebs or instance-store)

    • The root device name

    • The virtualization type (paravirtual or hvm)

    • The Hypervisor type (xen or ovm)

  2. Any Amazon EBS volumes associated with the instance. There will be one of the following for each volume:

    • The BLOCKDEVICE identifier

    • The device name

    • The ID of the snapshot

    • The volume size

    • Indicates whether the volume is deleted on instance termination (true orfalse)

    • The volume type

    • The IOPS provisioned for the volume (only valid for Provisioned IOPS (SSD) volumes)

    • The encryption status of the volume

  3. Any tags associated with the instance. There will be one of the following for each tag:

    • The TAG identifier

    • The resource type identifier

    • The ID of the resource

    • The tag key

    • The tag value

Amazon EC2 command line tools display errors on stderr.

Examples

Example 1

This example command describes the specified AMI.

PROMPT> ec2-describe-images ami-1a2b3c4d

IMAGE	ami-1a2b3c4d	amazon/getting-started-with-ebs-boot	amazon	available	public		i386	machine	aki-a13667e4	ari-a33667e6	ebs	paravirtual	xen
BLOCKDEVICEMAPPING	/dev/sda1		snap-1a2b3c4d	15	standard

Example 2

This example filters the response to include 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-1a2b3c4d    amazon/getting-started-with-ebs-boot	amazon	available	public		x86_64	machine			windows	ebs	hvm	xen
IMAGE   ami-2a2b3c4d    amazon/SqlSvrStd2003r2-x86_64-Win-v1.07	amazon	available	public		x86_64	machine			windows	instance-store	hvm	xen
...

Example 3

This example filters the results to display only images with an AWS Marketplace product code.

PROMPT> ec2-describe-images -F product-code.type=marketplace -o self

IMAGE	ami-1a2b3c4d	111122223333/My MP Image	111122223333	available	private	[marketplace: a1b2c3d4e5f6g7h8i9j10k11]	i386	machine				ebs	paravirtual	xen
BLOCKDEVICEMAPPING	/dev/sda1	snap-2de0d457	15	standard
BLOCKDEVICEMAPPING	/dev/sdb	snap-27e0d45d	100	standard
...