:doc:`ECRPublic <../../ecr-public>` / Client / describe_images

***************
describe_images
***************



.. py:method:: ECRPublic.Client.describe_images(**kwargs)

  

  Returns metadata that's related to the images in a repository in a public registry.

   

  .. note::

    

    Beginning with Docker version 1.9, the Docker client compresses image layers before pushing them to a V2 Docker registry. The output of the ``docker images`` command shows the uncompressed image size. Therefore, it might return a larger image size than the image sizes that are returned by  DescribeImages.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/ecr-public-2020-10-30/DescribeImages>`_  


  **Request Syntax**
  ::

    response = client.describe_images(
        registryId='string',
        repositoryName='string',
        imageIds=[
            {
                'imageDigest': 'string',
                'imageTag': 'string'
            },
        ],
        nextToken='string',
        maxResults=123
    )
    
  :type registryId: string
  :param registryId: 

    The Amazon Web Services account ID that's associated with the public registry that contains the repository where images are described. If you do not specify a registry, the default public registry is assumed.

    

  
  :type repositoryName: string
  :param repositoryName: **[REQUIRED]** 

    The repository that contains the images to describe.

    

  
  :type imageIds: list
  :param imageIds: 

    The list of image IDs for the requested repository.

    

  
    - *(dict) --* 

      An object with identifying information for an Amazon ECR image.

      

    
      - **imageDigest** *(string) --* 

        The ``sha256`` digest of the image manifest.

        

      
      - **imageTag** *(string) --* 

        The tag that's used for the image.

        

      
    

  :type nextToken: string
  :param nextToken: 

    The ``nextToken`` value that's returned from a previous paginated ``DescribeImages`` request where ``maxResults`` was used and the results exceeded the value of that parameter. Pagination continues from the end of the previous results that returned the ``nextToken`` value. If there are no more results to return, this value is ``null``. If you specify images with ``imageIds``, you can't use this option.

    

  
  :type maxResults: integer
  :param maxResults: 

    The maximum number of repository results that's returned by ``DescribeImages`` in paginated output. When this parameter is used, ``DescribeImages`` only returns ``maxResults`` results in a single page along with a ``nextToken`` response element. You can see the remaining results of the initial request by sending another ``DescribeImages`` request with the returned ``nextToken`` value. This value can be between 1 and 1000. If this parameter isn't used, then ``DescribeImages`` returns up to 100 results and a ``nextToken`` value, if applicable. If you specify images with ``imageIds``, you can't use this option.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'imageDetails': [
              {
                  'registryId': 'string',
                  'repositoryName': 'string',
                  'imageDigest': 'string',
                  'imageTags': [
                      'string',
                  ],
                  'imageSizeInBytes': 123,
                  'imagePushedAt': datetime(2015, 1, 1),
                  'imageManifestMediaType': 'string',
                  'artifactMediaType': 'string'
              },
          ],
          'nextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **imageDetails** *(list) --* 

        A list of  ImageDetail objects that contain data about the image.

        
        

        - *(dict) --* 

          An object that describes an image that's returned by a  DescribeImages operation.

          
          

          - **registryId** *(string) --* 

            The Amazon Web Services account ID that's associated with the public registry where this image belongs.

            
          

          - **repositoryName** *(string) --* 

            The name of the repository where this image belongs.

            
          

          - **imageDigest** *(string) --* 

            The ``sha256`` digest of the image manifest.

            
          

          - **imageTags** *(list) --* 

            The list of tags that's associated with this image.

            
            

            - *(string) --* 
        
          

          - **imageSizeInBytes** *(integer) --* 

            The size, in bytes, of the image in the repository.

             

            If the image is a manifest list, this is the max size of all manifests in the list.

             

            .. note::

              

              Beginning with Docker version 1.9, the Docker client compresses image layers before pushing them to a V2 Docker registry. The output of the ``docker images`` command shows the uncompressed image size, so it might return a larger image size than the image sizes that are returned by  DescribeImages.

              

            
          

          - **imagePushedAt** *(datetime) --* 

            The date and time, expressed in standard JavaScript date format, that the current image was pushed to the repository at.

            
          

          - **imageManifestMediaType** *(string) --* 

            The media type of the image manifest.

            
          

          - **artifactMediaType** *(string) --* 

            The artifact media type of the image.

            
      
    
      

      - **nextToken** *(string) --* 

        The ``nextToken`` value to include in a future ``DescribeImages`` request. When the results of a ``DescribeImages`` request exceed ``maxResults``, you can use this value to retrieve the next page of results. If there are no more results to return, this value is ``null``.

        
  
  **Exceptions**
  
  *   :py:class:`ECRPublic.Client.exceptions.ServerException`

  
  *   :py:class:`ECRPublic.Client.exceptions.InvalidParameterException`

  
  *   :py:class:`ECRPublic.Client.exceptions.RepositoryNotFoundException`

  
  *   :py:class:`ECRPublic.Client.exceptions.ImageNotFoundException`

  
  *   :py:class:`ECRPublic.Client.exceptions.UnsupportedCommandException`

  