:doc:`ECR <../../ecr>` / Client / describe_images

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



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

  

  Returns metadata about the images in a repository.

   

  .. note::

    

    Starting 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, Docker might return a larger image than the image shown in the Amazon Web Services Management Console.

    

   

  .. warning::

     

    The new version of Amazon ECR *Basic Scanning* doesn't use the  ImageDetail$imageScanFindingsSummary and  ImageDetail$imageScanStatus attributes from the API response to return scan results. Use the  DescribeImageScanFindings API instead. For more information about Amazon Web Services native basic scanning, see `Scan images for software vulnerabilities in Amazon ECR <https://docs.aws.amazon.com/AmazonECR/latest/userguide/image-scanning.html>`__.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/ecr-2015-09-21/DescribeImages>`_  


  **Request Syntax**
  ::

    response = client.describe_images(
        registryId='string',
        repositoryName='string',
        imageIds=[
            {
                'imageDigest': 'string',
                'imageTag': 'string'
            },
        ],
        nextToken='string',
        maxResults=123,
        filter={
            'tagStatus': 'TAGGED'|'UNTAGGED'|'ANY',
            'imageStatus': 'ACTIVE'|'ARCHIVED'|'ACTIVATING'|'ANY'
        }
    )
    
  :type registryId: string
  :param registryId: 

    The Amazon Web Services account ID associated with the registry that contains the repository in which to describe images. If you do not specify a registry, the default 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 image in an Amazon ECR repository.

      

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

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

        

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

        The tag used for the image.

        

      
    

  :type nextToken: string
  :param nextToken: 

    The ``nextToken`` value 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. This value is ``null`` when there are no more results to return. This option cannot be used when you specify images with ``imageIds``.

    

  
  :type maxResults: integer
  :param maxResults: 

    The maximum number of repository results 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. The remaining results of the initial request can be seen by sending another ``DescribeImages`` request with the returned ``nextToken`` value. This value can be between 1 and 1000. If this parameter is not used, then ``DescribeImages`` returns up to 100 results and a ``nextToken`` value, if applicable. This option cannot be used when you specify images with ``imageIds``.

    

  
  :type filter: dict
  :param filter: 

    The filter key and value with which to filter your ``DescribeImages`` results.

    

  
    - **tagStatus** *(string) --* 

      The tag status with which to filter your  DescribeImages results. You can filter results based on whether they are ``TAGGED`` or ``UNTAGGED``.

      

    
    - **imageStatus** *(string) --* 

      The image status with which to filter your  DescribeImages results. Valid values are ``ACTIVE``, ``ARCHIVED``, and ``ACTIVATING``.

      

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

    
    ::

      {
          'imageDetails': [
              {
                  'registryId': 'string',
                  'repositoryName': 'string',
                  'imageDigest': 'string',
                  'imageTags': [
                      'string',
                  ],
                  'imageSizeInBytes': 123,
                  'imagePushedAt': datetime(2015, 1, 1),
                  'imageScanStatus': {
                      'status': 'IN_PROGRESS'|'COMPLETE'|'FAILED'|'UNSUPPORTED_IMAGE'|'ACTIVE'|'PENDING'|'SCAN_ELIGIBILITY_EXPIRED'|'FINDINGS_UNAVAILABLE'|'LIMIT_EXCEEDED'|'IMAGE_ARCHIVED',
                      'description': 'string'
                  },
                  'imageScanFindingsSummary': {
                      'imageScanCompletedAt': datetime(2015, 1, 1),
                      'vulnerabilitySourceUpdatedAt': datetime(2015, 1, 1),
                      'findingSeverityCounts': {
                          'string': 123
                      }
                  },
                  'imageManifestMediaType': 'string',
                  'artifactMediaType': 'string',
                  'lastRecordedPullTime': datetime(2015, 1, 1),
                  'subjectManifestDigest': 'string',
                  'imageStatus': 'ACTIVE'|'ARCHIVED'|'ACTIVATING',
                  'lastArchivedAt': datetime(2015, 1, 1),
                  'lastActivatedAt': datetime(2015, 1, 1)
              },
          ],
          '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 returned by a  DescribeImages operation.

          
          

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

            The Amazon Web Services account ID associated with the registry to which this image belongs.

            
          

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

            The name of the repository to which this image belongs.

            
          

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

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

            
          

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

            The list of tags 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 will be the max size of all manifests in the list.

             

            .. note::

              

              Starting 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, Docker might return a larger image than the image shown in the Amazon Web Services Management Console.

              

            
          

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

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

            
          

          - **imageScanStatus** *(dict) --* 

            The current state of the scan.

            
            

            - **status** *(string) --* 

              The current state of an image scan.

              
            

            - **description** *(string) --* 

              The description of the image scan status.

              
        
          

          - **imageScanFindingsSummary** *(dict) --* 

            A summary of the last completed image scan.

            
            

            - **imageScanCompletedAt** *(datetime) --* 

              The time of the last completed image scan.

              
            

            - **vulnerabilitySourceUpdatedAt** *(datetime) --* 

              The time when the vulnerability data was last scanned.

              
            

            - **findingSeverityCounts** *(dict) --* 

              The image vulnerability counts, sorted by severity.

              
              

              - *(string) --* 
                

                - *(integer) --* 
          
        
        
          

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

            The media type of the image manifest.

            
          

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

            The artifact media type of the image.

            
          

          - **lastRecordedPullTime** *(datetime) --* 

            The date and time, expressed in standard JavaScript date format, when Amazon ECR recorded the last image pull.

             

            .. note::

              

              Amazon ECR refreshes the last image pull timestamp at least once every 24 hours. For example, if you pull an image once a day then the ``lastRecordedPullTime`` timestamp will indicate the exact time that the image was last pulled. However, if you pull an image once an hour, because Amazon ECR refreshes the ``lastRecordedPullTime`` timestamp at least once every 24 hours, the result may not be the exact time that the image was last pulled.

              

            
          

          - **subjectManifestDigest** *(string) --* 

            The digest of the subject manifest for images that are referrers.

            
          

          - **imageStatus** *(string) --* 

            The current status of the image.

            
          

          - **lastArchivedAt** *(datetime) --* 

            The date and time, expressed in standard JavaScript date format, when the image was last transitioned to Amazon ECR archive.

            
          

          - **lastActivatedAt** *(datetime) --* 

            The date and time, expressed in standard JavaScript date format, when the image was last restored from Amazon ECR archive to Amazon ECR standard.

            
      
    
      

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

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

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

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

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

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

  