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

***********
list_images
***********



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

  

  Lists all the image IDs for the specified repository.

   

  You can filter images based on whether or not they are tagged by using the ``tagStatus`` filter and specifying either ``TAGGED``, ``UNTAGGED`` or ``ANY``. For example, you can filter your results to return only ``UNTAGGED`` images and then pipe that result to a  BatchDeleteImage operation to delete them. Or, you can filter your results to return only ``TAGGED`` images to list all of the tags in your repository.

  

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


  **Request Syntax**
  ::

    response = client.list_images(
        registryId='string',
        repositoryName='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 list images. If you do not specify a registry, the default registry is assumed.

    

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

    The repository with image IDs to be listed.

    

  
  :type nextToken: string
  :param nextToken: 

    The ``nextToken`` value returned from a previous paginated ``ListImages`` 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.

     

    .. note::

      

      This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

      

    

  
  :type maxResults: integer
  :param maxResults: 

    The maximum number of image results returned by ``ListImages`` in paginated output. When this parameter is used, ``ListImages`` 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 ``ListImages`` request with the returned ``nextToken`` value. This value can be between 1 and 1000. If this parameter is not used, then ``ListImages`` returns up to 100 results and a ``nextToken`` value, if applicable.

    

  
  :type filter: dict
  :param filter: 

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

    

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

      The tag status with which to filter your  ListImages results.

      

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

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

      

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

    
    ::

      {
          'imageIds': [
              {
                  'imageDigest': 'string',
                  'imageTag': 'string'
              },
          ],
          'nextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **imageIds** *(list) --* 

        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.

            
      
    
      

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

        The ``nextToken`` value to include in a future ``ListImages`` request. When the results of a ``ListImages`` 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`

  

  **Examples**

  This example lists all of the images in the repository named ubuntu in the default registry in the current account. 
  ::

    response = client.list_images(
        repositoryName='ubuntu',
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'imageIds': [
            {
                'imageDigest': 'sha256:764f63476bdff6d83a09ba2a818f0d35757063724a9ac3ba5019c56f74ebf42a',
                'imageTag': 'precise',
            },
        ],
        'ResponseMetadata': {
            '...': '...',
        },
    }

  