Use DescribeImages with an Amazon SDK or CLI - Amazon Elastic Compute Cloud
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Use DescribeImages with an Amazon SDK or CLI

The following code examples show how to use DescribeImages.

Action examples are code excerpts from larger programs and must be run in context. You can see this action in context in the following code example:

Bash
Amazon CLI with Bash script
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

############################################################################### # function ec2_describe_images # # This function describes one or more Amazon Elastic Compute Cloud (Amazon EC2) images. # # Parameters: # -i image_ids - A space-separated list of image IDs (optional). # -h - Display help. # # And: # 0 - If successful. # 1 - If it fails. ############################################################################### function ec2_describe_images() { local image_ids response local option OPTARG # Required to use getopts command in a function. # bashsupport disable=BP5008 function usage() { echo "function ec2_describe_images" echo "Describes one or more Amazon Elastic Compute Cloud (Amazon EC2) images." echo " -i image_ids - A space-separated list of image IDs (optional)." echo " -h - Display help." echo "" } # Retrieve the calling parameters. while getopts "i:h" option; do case "${option}" in i) image_ids="${OPTARG}" ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done export OPTIND=1 local aws_cli_args=() if [[ -n "$image_ids" ]]; then # shellcheck disable=SC2206 aws_cli_args+=("--image-ids" $image_ids) fi response=$(aws ec2 describe-images \ "${aws_cli_args[@]}" \ --query 'Images[*].[Description,Architecture,ImageId]' \ --output text) || { aws_cli_error_log ${?} errecho "ERROR: AWS reports describe-images operation failed.$response" return 1 } echo "$response" return 0 }

The utility functions used in this example.

############################################################################### # function errecho # # This function outputs everything sent to it to STDERR (standard error output). ############################################################################### function errecho() { printf "%s\n" "$*" 1>&2 } ############################################################################## # function aws_cli_error_log() # # This function is used to log the error messages from the AWS CLI. # # The function expects the following argument: # $1 - The error code returned by the AWS CLI. # # Returns: # 0: - Success. # ############################################################################## function aws_cli_error_log() { local err_code=$1 errecho "Error code : $err_code" if [ "$err_code" == 1 ]; then errecho " One or more S3 transfers failed." elif [ "$err_code" == 2 ]; then errecho " Command line failed to parse." elif [ "$err_code" == 130 ]; then errecho " Process received SIGINT." elif [ "$err_code" == 252 ]; then errecho " Command syntax invalid." elif [ "$err_code" == 253 ]; then errecho " The system environment or configuration was invalid." elif [ "$err_code" == 254 ]; then errecho " The service returned an error." elif [ "$err_code" == 255 ]; then errecho " 255 is a catch-all error." fi return 0 }
  • For API details, see DescribeImages in Amazon CLI Command Reference.

CLI
Amazon CLI

Example 1: To describe an AMI

The following describe-images example describes the specified AMI in the specified Region.

aws ec2 describe-images \ --region us-east-1 \ --image-ids ami-1234567890EXAMPLE

Output:

{ "Images": [ { "VirtualizationType": "hvm", "Description": "Provided by Red Hat, Inc.", "PlatformDetails": "Red Hat Enterprise Linux", "EnaSupport": true, "Hypervisor": "xen", "State": "available", "SriovNetSupport": "simple", "ImageId": "ami-1234567890EXAMPLE", "UsageOperation": "RunInstances:0010", "BlockDeviceMappings": [ { "DeviceName": "/dev/sda1", "Ebs": { "SnapshotId": "snap-111222333444aaabb", "DeleteOnTermination": true, "VolumeType": "gp2", "VolumeSize": 10, "Encrypted": false } } ], "Architecture": "x86_64", "ImageLocation": "123456789012/RHEL-8.0.0_HVM-20190618-x86_64-1-Hourly2-GP2", "RootDeviceType": "ebs", "OwnerId": "123456789012", "RootDeviceName": "/dev/sda1", "CreationDate": "2019-05-10T13:17:12.000Z", "Public": true, "ImageType": "machine", "Name": "RHEL-8.0.0_HVM-20190618-x86_64-1-Hourly2-GP2" } ] }

For more information, see Amazon Machine Images (AMI) in the Amazon EC2 User Guide.

Example 2: To describe AMIs based on filters

The following describe-images example describes Windows AMIs provided by Amazon that are backed by Amazon EBS.

aws ec2 describe-images \ --owners amazon \ --filters "Name=platform,Values=windows" "Name=root-device-type,Values=ebs"

For an example of the output for describe-images, see Example 1.

For additional examples using filters, see Listing and filtering your resources in the Amazon EC2 User Guide.

Example 3: To describe AMIs based on tags

The following describe-images example describes all AMIs that have the tag Type=Custom. The example uses the --query parameter to display only the AMI IDs.

aws ec2 describe-images \ --filters "Name=tag:Type,Values=Custom" \ --query 'Images[*].[ImageId]' \ --output text

Output:

ami-1234567890EXAMPLE ami-0abcdef1234567890

For additional examples using tag filters, see Working with tags in the Amazon EC2 User Guide.

  • For API details, see DescribeImages in Amazon CLI Command Reference.

JavaScript
SDK for JavaScript (v3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

import { EC2Client, paginateDescribeImages } from "@aws-sdk/client-ec2"; /** * Describes the specified images (AMIs, AKIs, and ARIs) available to you or all of the images available to you. * @param {{ architecture: string, pageSize: number }} options */ export const main = async ({ architecture, pageSize }) => { pageSize = Number.parseInt(pageSize); const client = new EC2Client({}); // The paginate function is a wrapper around the base command. const paginator = paginateDescribeImages( // Without limiting the page size, this call can take a long time. pageSize is just sugar for // the MaxResults property in the base command. { client, pageSize }, { // There are almost 70,000 images available. Be specific with your filtering // to increase efficiency. // See https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-ec2/interfaces/describeimagescommandinput.html#filters Filters: [{ Name: "architecture", Values: [architecture] }], }, ); /** * @type {import('@aws-sdk/client-ec2').Image[]} */ const images = []; let recordsScanned = 0; try { for await (const page of paginator) { recordsScanned += pageSize; if (page.Images.length) { images.push(...page.Images); break; } console.log( `No matching image found yet. Searched ${recordsScanned} records.`, ); } if (images.length) { console.log( `Found ${images.length} images:\n\n${images.map((image) => image.Name).join("\n")}\n`, ); } else { console.log( `No matching images found. Searched ${recordsScanned} records.\n`, ); } return images; } catch (caught) { if (caught instanceof Error && caught.name === "InvalidParameterValue") { console.warn(`${caught.message}`); return []; } throw caught; } };
  • For API details, see DescribeImages in Amazon SDK for JavaScript API Reference.

PowerShell
Tools for PowerShell

Example 1: This example describes the specified AMI.

Get-EC2Image -ImageId ami-12345678

Output:

Architecture : x86_64 BlockDeviceMappings : {/dev/xvda} CreationDate : 2014-10-20T00:56:28.000Z Description : My image Hypervisor : xen ImageId : ami-12345678 ImageLocation : 123456789012/my-image ImageOwnerAlias : ImageType : machine KernelId : Name : my-image OwnerId : 123456789012 Platform : ProductCodes : {} Public : False RamdiskId : RootDeviceName : /dev/xvda RootDeviceType : ebs SriovNetSupport : simple State : available StateReason : Tags : {Name} VirtualizationType : hvm

Example 2: This example describes the AMIs that you own.

Get-EC2Image -owner self

Example 3: This example describes the public AMIs that run Microsoft Windows Server.

Get-EC2Image -Filter @{ Name="platform"; Values="windows" }

Example 4: This example describes all public AMIs in the 'us-west-2' region.

Get-EC2Image -Region us-west-2
  • For API details, see DescribeImages in Amazon Tools for PowerShell Cmdlet Reference.

Python
SDK for Python (Boto3)
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

class EC2InstanceWrapper: """Encapsulates Amazon Elastic Compute Cloud (Amazon EC2) instance actions using the client interface.""" def __init__( self, ec2_client: Any, instances: Optional[List[Dict[str, Any]]] = None ) -> None: """ Initializes the EC2InstanceWrapper with an EC2 client and optional instances. :param ec2_client: A Boto3 Amazon EC2 client. This client provides low-level access to AWS EC2 services. :param instances: A list of dictionaries representing Boto3 Instance objects. These are high-level objects that wrap instance actions. """ self.ec2_client = ec2_client self.instances = instances or [] @classmethod def from_client(cls) -> "EC2InstanceWrapper": """ Creates an EC2InstanceWrapper instance with a default EC2 client. :return: An instance of EC2InstanceWrapper initialized with the default EC2 client. """ ec2_client = boto3.client("ec2") return cls(ec2_client) def get_images(self, image_ids: List[str]) -> List[Dict[str, Any]]: """ Gets information about Amazon Machine Images (AMIs) from a list of AMI IDs. :param image_ids: The list of AMI IDs to look up. :return: A list of dictionaries representing the requested AMIs. """ try: response = self.ec2_client.describe_images(ImageIds=image_ids) images = response["Images"] except ClientError as err: logger.error(f"Failed to stop AMI(s): {','.join(map(str, image_ids))}") error_code = err.response["Error"]["Code"] if error_code == "InvalidAMIID.NotFound": logger.error("One or more of the AMI IDs does not exist.") raise return images
  • For API details, see DescribeImages in Amazon SDK for Python (Boto3) API Reference.

Rust
SDK for Rust
Note

There's more on GitHub. Find the complete example and learn how to set up and run in the Amazon Code Examples Repository.

pub async fn list_images(&self, ids: Vec<Parameter>) -> Result<Vec<Image>, EC2Error> { let image_ids = ids.into_iter().filter_map(|p| p.value).collect(); let output = self .client .describe_images() .set_image_ids(Some(image_ids)) .send() .await?; let images = output.images.unwrap_or_default(); if images.is_empty() { Err(EC2Error::new("No images for selected AMIs")) } else { Ok(images) } }

Using the list_images function with SSM to limit based on your environment. For more details on SSM, see https://docs.aws.amazon.com/systems-manager/latest/userguide/example_ssm_GetParameters_section.html.

async fn find_image(&mut self) -> Result<ScenarioImage, EC2Error> { let params: Vec<Parameter> = self .ssm .list_path("/aws/service/ami-amazon-linux-latest") .await .map_err(|e| e.add_message("Could not find parameters for available images"))? .into_iter() .filter(|param| param.name().is_some_and(|name| name.contains("amzn2"))) .collect(); let amzn2_images: Vec<ScenarioImage> = self .ec2 .list_images(params) .await .map_err(|e| e.add_message("Could not find images"))? .into_iter() .map(ScenarioImage::from) .collect(); println!("We will now create an instance from an Amazon Linux 2 AMI"); let ami = self.util.select_scenario_image(amzn2_images)?; Ok(ami) }
  • For API details, see DescribeImages in Amazon SDK for Rust API reference.

For a complete list of Amazon SDK developer guides and code examples, see Create Amazon EC2 resources using an Amazon SDK. This topic also includes information about getting started and details about previous SDK versions.