github.com/hanks177/podman/v4@v4.1.3-0.20220613032544-16d90015bc83/docs/source/markdown/podman-search.1.md (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 will be 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 will only work 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  #### **--authfile**=*path*
    34  
    35  Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json
    36  
    37  Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
    38  environment variable. `export REGISTRY_AUTH_FILE=path`
    39  
    40  #### **--compatible**
    41  
    42  After the name and the description, also show the stars, official and automated descriptors as Docker does.
    43  Podman does not show these descriptors by default since they are not supported by most public container registries.
    44  
    45  #### **--filter**, **-f**=*filter*
    46  
    47  Filter output based on conditions provided (default [])
    48  
    49  Supported filters are:
    50  
    51  * stars (int - number of stars the image has)
    52  * is-automated (boolean - true | false) - is the image automated or not
    53  * is-official (boolean - true | false) - is the image official or not
    54  
    55  #### **--format**=*format*
    56  
    57  Change the output format to a Go template
    58  
    59  Valid placeholders for the Go template are listed below:
    60  
    61  | **Placeholder** | **Description**              |
    62  | --------------- | ---------------------------- |
    63  | .Index          | Registry                     |
    64  | .Name           | Image name                   |
    65  | .Description    | Image description            |
    66  | .Stars          | Star count of image          |
    67  | .Official       | "[OK]" if image is official  |
    68  | .Automated      | "[OK]" if image is automated |
    69  | .Tag            | Repository tag               |
    70  
    71  Note: use .Tag only if the --list-tags is set.
    72  
    73  #### **--help**, **-h**
    74  
    75  Print usage statement
    76  
    77  #### **--limit**=*limit*
    78  
    79  Limit the number of results (default 25).
    80  Note: The results from each registry will be limited to this value.
    81  Example if limit is 10 and two registries are being searched, the total
    82  number of results will be 20, 10 from each (if there are at least 10 matches in each).
    83  The order of the search results is the order in which the API endpoint returns the results.
    84  
    85  #### **--list-tags**
    86  
    87  List the available tags in the repository for the specified image.
    88  **Note:** --list-tags requires the search term to be a fully specified image name.
    89  The result contains the Image name and its tag, one line for every tag associated with the image.
    90  
    91  #### **--no-trunc**
    92  
    93  Do not truncate the output (default *false*).
    94  
    95  #### **--tls-verify**
    96  
    97  Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true,
    98  then TLS verification will be used. If set to false, then TLS verification will not be used if needed. If not specified,
    99  default registries will be searched through (in /etc/containers/registries.conf), and TLS will be skipped if a default
   100  registry is listed in the insecure registries.
   101  
   102  ## EXAMPLES
   103  
   104  ```
   105  $ podman search --limit 3 fedora
   106  NAME                                     DESCRIPTION
   107  registry.centos.org/centos
   108  registry.centos.org/cdrage/mosh-centos7
   109  registry.centos.org/centos/bind
   110  docker.io/library/centos                 The official build of CentOS.
   111  docker.io/jdeathe/centos-ssh             OpenSSH / Supervisor / EPEL/IUS/SCL Repos - ...
   112  docker.io/ansible/centos7-ansible        Ansible on Centos7
   113  quay.io/centos/centos                    The official CentOS base containers.
   114  quay.io/ukhomeofficedigital/centos-base
   115  quay.io/quarkus/centos-quarkus-maven     Quarkus.io builder image for building Quarku...
   116  ```
   117  
   118  Note that the Stars, Official and Automated descriptors are only available on Docker Hub and are hence not displayed by default.
   119  ```
   120  $ podman search --format "{{.Name}}\t{{.Stars}}\t{{.Official}}" alpine --limit 3
   121  docker.io/library/alpine       7956        [OK]
   122  docker.io/alpine/git           192
   123  docker.io/anapsix/alpine-java  474
   124  quay.io/libpod/alpine          0
   125  quay.io/vqcomms/alpine-tools   0
   126  quay.io/wire/alpine-deps       0
   127  ```
   128  
   129  ```
   130  $ podman search --list-tags registry.access.redhat.com/ubi8 --limit 4
   131  NAME                             TAG
   132  registry.access.redhat.com/ubi8  8.4-211
   133  registry.access.redhat.com/ubi8  8.4-206.1626828523-source
   134  registry.access.redhat.com/ubi8  8.4-199
   135  registry.access.redhat.com/ubi8  8.4-211-source
   136  
   137  ```
   138  Note: This works only with registries that implement the v2 API. If tried with a v1 registry an error will be returned.
   139  
   140  ## FILES
   141  
   142  **registries.conf** (`/etc/containers/registries.conf`)
   143  
   144  registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.
   145  
   146  ## SEE ALSO
   147  **[podman(1)](podman.1.md)**, **[containers-registries(5)](https://github.com/containers/image/blob/main/docs/containers-registries.5.md)**
   148  
   149  ## HISTORY
   150  January 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com>