v2

latestSwagger 2.0raw.githubusercontent.com2025-09-17107133447.6 KB

Image

List Images

Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.

get/images/json

Query parameters

allboolean

Show all images. Only images from a final layer (no children) are shown by default.

filtersstring

A JSON encoded value of the filters (a map[string][]string) to process on the images list.

Available filters:

before=(<image-name>[:<tag>], <image id> or <image@digest>)
dangling=true
label=key or label="key=value" of an image label
reference=(<image-name>[:<tag>])
since=(<image-name>[:<tag>], <image id> or <image@digest>)
until=<timestamp>

shared-sizeboolean

Compute and show shared size as a SharedSize field on each image.

digestsboolean

Show digest information as a RepoDigests field on each image.

manifestsboolean

Include Manifests in the image summary.

Response

Summary image data for the images matching the query

Idstring required

ID is the content-addressable ID of an image.

This identifier is a content-addressable digest calculated from the image's configuration (which includes the digests of layers used by the image).

Note that this digest differs from the RepoDigests below, which holds digests of image manifests that reference the image.

ParentIdstring required

ID of the parent image.

Depending on how the image was created, this field may be empty and is only set for images that were built/created locally. This field is empty if the image was pulled from an image registry.

RepoTagsstring[] required

List of image names/tags in the local image cache that reference this image.

Multiple image tags can refer to the same image, and this list may be empty if no tags reference the image, in which case the image is "untagged", in which case it can still be referenced by its ID.

RepoDigestsstring[] required

List of content-addressable digests of locally available image manifests that the image is referenced from. Multiple manifests can refer to the same image.

These digests are usually only available if the image was either pulled from a registry, or if the image was pushed to a registry, which is when the manifest is generated and its digest calculated.

Createdinteger required

Date and time at which the image was created as a Unix timestamp (number of seconds since EPOCH).

Sizeinteger required

Total size of the image including all layers it is composed of.

SharedSizeinteger required

Total size of image layers that are shared between this image and other images.

This size is not calculated by default. -1 indicates that the value has not been set / calculated.

VirtualSizeinteger

Total size of the image including all layers it is composed of.

Deprecated: this field is omitted in API v1.44, but kept for backward compatibility. Use Size instead.

Labelsobject required

User-defined key/value metadata.

Containersinteger required

Number of containers using this image. Includes both stopped and running containers.

-1 indicates that the value has not been set / calculated.

Example response

[
  {
    "Id": "sha256:ec3f0931a6e6b6855d76b2d7b0be30e81860baccd891b2e243280bf1cd8ad710",
    "RepoTags": [
      "example:1.0",
      "example:latest",
      "example:stable",
      "internal.registry.example.com:5000/example:1.0"
    ],
    "RepoDigests": [
      "example@sha256:afcc7f1ac1b49db317a7196c902e61c6c3c4607d63599ee1a82d702d249a0ccb",
      "internal.registry.example.com:5000/example@sha256:b69959407d21e8a062e0416bf13405bb2b71ed7a84dde4158ebafacfa06f5578"
    ],
    "Size": 172064416,
    "SharedSize": 1239828,
    "VirtualSize": 172064416,
    "Labels": {
      "com.example.some-label": "some-value",
      "com.example.some-other-label": "some-other-value"
    },
    "Containers": 2,
    "Manifests": [
      {
        "ID": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f",
        "Descriptor": {
          "mediaType": "application/vnd.oci.image.manifest.v1+json",
          "digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
          "size": 424,
          "annotations": {
            "com.docker.official-images.bashbrew.arch": "amd64",
            "org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
            "org.opencontainers.image.base.name": "scratch",
            "org.opencontainers.image.created": "2025-01-27T00:00:00Z",
            "org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
            "org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
            "org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
            "org.opencontainers.image.version": "24.04"
          },
          "platform": {
            "architecture": "arm",
            "os": "windows",
            "os.version": "10.0.19041.1165",
            "os.features": [
              "win32k"
            ],
            "variant": "v7"
          }
        },
        "Available": true,
        "Size": {
          "Total": 8213251,
          "Content": 3987495
        },
        "Kind": "image",
        "ImageData": {
          "Platform": {
            "architecture": "arm",
            "os": "windows",
            "os.version": "10.0.19041.1165",
            "os.features": [
              "win32k"
            ],
            "variant": "v7"
          },
          "Containers": [
            "ede54ee1fda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c7430",
            "abadbce344c096744d8d6071a90d474d28af8f1034b5ea9fb03c3f4bfc6d005e"
          ],
          "Size": {
            "Unpacked": 3987495
          }
        },
        "AttestationData": {
          "For": "sha256:95869fbcf224d947ace8d61d0e931d49e31bb7fc67fffbbe9c3198c33aa8e93f"
        }
      }
    ],
    "Descriptor": {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:c0537ff6a5218ef531ece93d4984efc99bbf3f7497c0a7726c88e2bb7584dc96",
      "size": 424,
      "annotations": {
        "com.docker.official-images.bashbrew.arch": "amd64",
        "org.opencontainers.image.base.digest": "sha256:0d0ef5c914d3ea700147da1bd050c59edb8bb12ca312f3800b29d7c8087eabd8",
        "org.opencontainers.image.base.name": "scratch",
        "org.opencontainers.image.created": "2025-01-27T00:00:00Z",
        "org.opencontainers.image.revision": "9fabb4bad5138435b01857e2fe9363e2dc5f6a79",
        "org.opencontainers.image.source": "https://git.launchpad.net/cloud-images/+oci/ubuntu-base",
        "org.opencontainers.image.url": "https://hub.docker.com/_/ubuntu",
        "org.opencontainers.image.version": "24.04"
      },
      "platform": {
        "architecture": "arm",
        "os": "windows",
        "os.version": "10.0.19041.1165",
        "os.features": [
          "win32k"
        ],
        "variant": "v7"
      }
    }
  }
]