DescribeImages

Lists the machine images available to you.

Every image returned is one we publish. There are no public images from other accounts, no marketplace and no customer-built images — see Machine images for the shelf itself.

Paginated.

Request

Parameter	Type	Constraints
`ImageId.N`	list	`ami-` followed by 8 or 17 hex characters
`Filter.N`	list	See below
`MaxResults`	integer	5–1000
`NextToken`	string	Opaque
`Owner.N`	list	Only `self` and our own account resolve. Others match nothing
`ExecutableUsers.N`	list	Accepted; there are no shared images, so it never narrows anything
`DryRun`	boolean

Omitting MaxResults returns up to 1000 per page.

Filters

Filter	Matches
`name`	The image name, e.g. `debian-13`. Wildcards allowed
`image-id`
`architecture`	`x86_64` — the only architecture
`state`	`available`
`root-device-type`, `root-device-name`
`virtualization-type`	`hvm`
`creation-date`	Wildcards allowed
`description`
`tag:<key>`, `tag-key`

Filters naming things this platform never reports — product codes, billing products, image ownership by other accounts, deprecation times, TPM and boot-mode attributes — return InvalidParameterValue naming the filter, rather than matching nothing silently.

Response

Element	Notes
`imageId`	`ami-…`
`name`	`debian-13`, `ubuntu-24.04`, …
`description`	States the login user for that image
`imageState`	`available`
`architecture`	`x86_64`
`creationDate`	When we imported it
`rootDeviceType`, `rootDeviceName`
`virtualizationType`	`hvm`
`hypervisor`
`imageOwnerAlias`	Ours
`public`	`true` — every image we publish is available to every account
`blockDeviceMapping`	The root device and its minimum size
`tagSet`

[!primary]

Read the login user out of description. It is set by the distribution, not by us, and using the wrong one produces a Permission denied (publickey) that looks exactly like a broken key. That mistake costs more support time than anything else on this platform.

Elements the platform does not have — product codes, deprecation time, imdsSupport, bootMode, tpmSupport, sriovNetSupport, enaSupport, platformDetails, usageOperation — are omitted rather than invented.

Names roll, ids change

An image name points at the newest build we have imported. When we import a newer upstream build, the name moves to it and the ami- id changes.

If you	Then
Look up by name at deploy time	You get the newest build — usually what you want
Pin a literal `ami-…`	You get that exact build until it is withdrawn
Need bytes that cannot change for months	Record the image checksum, not the id

This is deliberate: upstream vendors publish rolling latest builds, and re-importing is how the shelf stays patched.

[!warning]

A stored ami- id is not a guarantee of identical bytes over time. Recording a fingerprint per image id is a known gap. Pin by checksum if immutability matters to you.

Errors

Code	Status	Cause
`InvalidAMIID.Malformed`	400	The id is not the right shape
`InvalidAMIID.NotFound`	400	No such image
`InvalidParameterValue`	400	An unsupported filter, or `MaxResults` out of range
`InvalidPaginationToken`	400	Expired or issued for different filters

Examples

alias sc='aws --endpoint-url https://ec2.shelfcs.com --region hel1'

sc ec2 describe-images \
  --query 'Images[].[ImageId,Name,Description,CreationDate]' --output table

sc ec2 describe-images --filters Name=name,Values='debian-*'

data "aws_ami" "debian" {
  most_recent = true

  filter {
    name   = "name"
    values = ["debian-13"]
  }
}

resource "aws_instance" "app" {
  ami           = data.aws_ami.debian.id
  instance_type = "cd-standard-2-4"
}

most_recent = true with a name filter is the right pattern here: the name is stable, the id behind it is not.

imgs = ec2.describe_images(Filters=[{"Name": "name", "Values": ["ubuntu-24.04"]}])
img = sorted(imgs["Images"], key=lambda i: i["CreationDate"])[-1]
print(img["ImageId"], img["Description"])   # description names the login user

Not implemented

CreateImage, RegisterImage, CopyImage, DeregisterImage, ModifyImageAttribute and ResetImageAttribute return InvalidAction. You cannot build or share an image on this platform yet.

DescribeImageAttribute is available for the attributes the response above carries.

Go further

Machine images — the shelf, with login users
RunInstances
Instance types
Image and catalogue actions