github.com/containers/podman/v5@v5.1.0-rc1/docs/source/markdown/podman-search.1.md.in (about)

     1  % podman-search 1
     2  
     3  ## NAME
     4  podman\-search - Search a registry for an image
     5  
     6  ## SYNOPSIS
     7  **podman search** [*options*] *term*
     8  
     9  ## DESCRIPTION
    10  **podman search** searches a registry or a list of registries for a matching image.
    11  The user can specify which registry to search by prefixing the registry in the search term
    12  (e.g., **registry.fedoraproject.org/fedora**).  By default, all
    13  unqualified-search registries in `containers-registries.conf(5)` are used.
    14  
    15  The default number of results is 25. The number of results can be limited using the **--limit** flag.
    16  If more than one registry is being searched, the limit is applied to each registry. The output can be filtered
    17  using the **--filter** flag. To get all available images in a registry without a specific
    18  search term, the user can just enter the registry name with a trailing "/" (example **registry.fedoraproject.org/**).
    19  
    20  Note that **podman search** is not a reliable way to determine the presence or existence of an image.
    21  The search behavior of the v1 and v2 Docker distribution API is specific to the implementation of each registry.
    22  Some registries may not support searching at all.
    23  Further note that searching without a search term only works for registries that implement the v2 API.
    24  
    25  **podman [GLOBAL OPTIONS]**
    26  
    27  **podman search [GLOBAL OPTIONS]**
    28  
    29  **podman search [OPTIONS] TERM**
    30  
    31  ## OPTIONS
    32  
    33  @@option authfile
    34  
    35  @@option cert-dir
    36  
    37  #### **--compatible**
    38  
    39  After the name and the description, also show the stars, official and automated descriptors as Docker does.
    40  Podman does not show these descriptors by default since they are not supported by most public container registries.
    41  
    42  @@option creds
    43  
    44  #### **--filter**, **-f**=*filter*
    45  
    46  Filter output based on conditions provided (default [])
    47  
    48  Supported filters are:
    49  
    50  * stars (int) - minimum number of stars required for images to show
    51  * is-automated (boolean - true | false) - is the image automated or not
    52  * is-official (boolean - true | false) - is the image official or not
    53  
    54  #### **--format**=*format*
    55  
    56  Change the output format to a Go template
    57  
    58  Valid placeholders for the Go template are listed below:
    59  
    60  | **Placeholder** | **Description**              |
    61  | --------------- | ---------------------------- |
    62  | .Automated      | "[OK]" if image is automated |
    63  | .Description    | Image description            |
    64  | .Index          | Registry                     |
    65  | .Name           | Image name                   |
    66  | .Official       | "[OK]" if image is official  |
    67  | .Stars          | Star count of image          |
    68  | .Tag            | Repository tag               |
    69  
    70  Note: use .Tag only if the --list-tags is set.
    71  
    72  #### **--help**, **-h**
    73  
    74  Print usage statement
    75  
    76  #### **--limit**=*limit*
    77  
    78  Limit the number of results (default 25).
    79  Note: The results from each registry is limited to this value.
    80  Example if limit is 10 and two registries are being searched, the total
    81  number of results is 20, 10 from each (if there are at least 10 matches in each).
    82  The order of the search results is the order in which the API endpoint returns the results.
    83  
    84  #### **--list-tags**
    85  
    86  List the available tags in the repository for the specified image.
    87  **Note:** --list-tags requires the search term to be a fully specified image name.
    88  The result contains the Image name and its tag, one line for every tag associated with the image.
    89  
    90  #### **--no-trunc**
    91  
    92  Do not truncate the output (default *false*).
    93  
    94  @@option tls-verify
    95  
    96  ## EXAMPLES
    97  
    98  Search for images containing the specified name, returning the first three images from each defined registry.
    99  ```
   100  $ podman search --limit 3 fedora
   101  NAME                                     DESCRIPTION
   102  NAME                                           DESCRIPTION
   103  registry.fedoraproject.org/f29/fedora-toolbox
   104  registry.fedoraproject.org/f30/fedora-toolbox
   105  registry.fedoraproject.org/f31/fedora-toolbox
   106  docker.io/library/fedora                       Official Docker builds of Fedora
   107  docker.io/kasmweb/fedora-37-desktop            Fedora 37 desktop for Kasm Workspaces
   108  docker.io/kasmweb/fedora-38-desktop            Fedora 38 desktop for Kasm Workspaces
   109  quay.io/fedora/fedora
   110  quay.io/containerdisks/fedora                  # Fedora Containerdisk Images  <img src="htt...
   111  quay.io/fedora/fedora-minimal
   112  ```
   113  
   114  Note that the Stars, Official and Automated descriptors are only available on Docker Hub and are hence not displayed by default.
   115  ```
   116  $ podman search --format "{{.Name}}\t{{.Stars}}\t{{.Official}}" alpine --limit 3
   117  docker.io/library/alpine       7956        [OK]
   118  docker.io/alpine/git           192
   119  docker.io/anapsix/alpine-java  474
   120  quay.io/libpod/alpine          0
   121  quay.io/vqcomms/alpine-tools   0
   122  quay.io/wire/alpine-deps       0
   123  ```
   124  
   125  Search and list tags for the specified image returning the first four images from each defined registry.
   126  ```
   127  $ podman search --list-tags registry.access.redhat.com/ubi8 --limit 4
   128  NAME                             TAG
   129  registry.access.redhat.com/ubi8  8.4-211
   130  registry.access.redhat.com/ubi8  8.4-206.1626828523-source
   131  registry.access.redhat.com/ubi8  8.4-199
   132  registry.access.redhat.com/ubi8  8.4-211-source
   133  ```
   134  Note: This works only with registries that implement the v2 API. If tried with a v1 registry an error is returned.
   135  
   136  ## FILES
   137  
   138  **registries.conf** (`/etc/containers/registries.conf`)
   139  
   140  registries.conf is the configuration file which specifies which container registries is consulted when completing image names which do not include a registry or domain portion.
   141  
   142  ## SEE ALSO
   143  **[podman(1)](podman.1.md)**, **[containers-registries(5)](https://github.com/containers/image/blob/main/docs/containers-registries.5.md)**
   144  
   145  ## HISTORY
   146  January 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com>