podman-search(1) General Commands Manual podman-search(1)
NAME
podman-search - Search a registry for an image
SYNOPSIS
podman search [options] term
DESCRIPTION
podman search searches a registry or a list of registries for a matching
image. The user can specify which registry to search by prefixing the
registry in the search term (e.g., registry.fedoraproject.org/fedora).
By default, all unqualified-search registries in containers-reg-
istries.conf(5) are used.
The default number of results is 25. The number of results can be lim-
ited using the --limit flag. If more than one registry is being
searched, the limit is applied to each registry. The output can be fil-
tered using the --filter flag. To get all available images in a registry
without a specific search term, the user can just enter the registry
name with a trailing "/" (example registry.fedoraproject.org/).
Note that podman search is not a reliable way to determine the presence
or existence of an image. The search behavior of the v1 and v2 Docker
distribution API is specific to the implementation of each registry.
Some registries may not support searching at all. Further note that
searching without a search term only works for registries that implement
the v2 API.
podman [GLOBAL OPTIONS]
podman search [GLOBAL OPTIONS]
podman search [OPTIONS] TERM
OPTIONS
--authfile=path
Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain-
ers/auth.json on Linux, and $HOME/.config/containers/auth.json on Win-
dows/macOS. The file is created by podman login. If the authorization
state is not found there, $HOME/.docker/config.json is checked, which is
set using docker login.
Note: There is also the option to override the default path of the au-
thentication file by setting the REGISTRY_AUTH_FILE environment vari-
able. This can be done with export REGISTRY_AUTH_FILE=path.
--cert-dir=path
Use certificates at path (*.crt, *.cert, *.key) to connect to the reg-
istry. (Default: /etc/containers/certs.d) For details, see containers-
certs.d(5). (This option is not available with the remote Podman
client, including Mac and Windows (excluding WSL2) machines)
--compatible
After the name and the description, also show the stars, official and
automated descriptors as Docker does. Podman does not show these de-
scriptors by default since they are not supported by most public con-
tainer registries.
--creds=[username[:password]]
The [username[:password]] to use to authenticate with the registry, if
required. If one or both values are not supplied, a command line prompt
appears and the value can be entered. The password is entered without
echo.
Note that the specified credentials are only used to authenticate
against target registries. They are not used for mirrors or when the
registry gets rewritten (see containers-registries.conf(5)); to authen-
ticate against those consider using a containers-auth.json(5) file.
--filter, -f=filter
Filter output based on conditions provided (default [])
Supported filters are:
• stars (int) - minimum number of stars required for images to
show
• is-automated (boolean - true | false) - is the image automated
or not
• is-official (boolean - true | false) - is the image official or
not
--format=format
Change the output format to a Go template
Valid placeholders for the Go template are listed below:
┌──────────────┬──────────────────────────────┐
│ Placeholder │ Description │
├──────────────┼──────────────────────────────┤
│ .Automated │ "[OK]" if image is automated │
├──────────────┼──────────────────────────────┤
│ .Description │ Image description │
├──────────────┼──────────────────────────────┤
│ .Index │ Registry │
├──────────────┼──────────────────────────────┤
│ .Name │ Image name │
├──────────────┼──────────────────────────────┤
│ .Official │ "[OK]" if image is official │
├──────────────┼──────────────────────────────┤
│ .Stars │ Star count of image │
├──────────────┼──────────────────────────────┤
│ .Tag │ Repository tag │
└──────────────┴──────────────────────────────┘
Note: use .Tag only if the --list-tags is set.
--help, -h
Print usage statement
--limit=limit
Limit the number of results (default 25). Note: The results from each
registry is limited to this value. Example if limit is 10 and two reg-
istries are being searched, the total number of results is 20, 10 from
each (if there are at least 10 matches in each). The order of the
search results is the order in which the API endpoint returns the re-
sults.
--list-tags
List the available tags in the repository for the specified image.
Note: --list-tags requires the search term to be a fully specified image
name. The result contains the Image name and its tag, one line for
every tag associated with the image.
--no-trunc
Do not truncate the output (default false).
--tls-verify
Require HTTPS and verify certificates when contacting registries (de-
fault: true). If explicitly set to true, TLS verification is used. If
set to false, TLS verification is not used. If not specified, TLS veri-
fication is used unless the target registry is listed as an insecure
registry in containers-registries.conf(5)
EXAMPLES
Search for images containing the specified name, returning the first
three images from each defined registry.
$ podman search --limit 3 fedora
NAME DESCRIPTION
NAME DESCRIPTION
registry.fedoraproject.org/f29/fedora-toolbox
registry.fedoraproject.org/f30/fedora-toolbox
registry.fedoraproject.org/f31/fedora-toolbox
docker.io/library/fedora Official Docker builds of Fedora
docker.io/kasmweb/fedora-37-desktop Fedora 37 desktop for Kasm Workspaces
docker.io/kasmweb/fedora-38-desktop Fedora 38 desktop for Kasm Workspaces
quay.io/fedora/fedora
quay.io/containerdisks/fedora # Fedora Containerdisk Images <img src="htt...
quay.io/fedora/fedora-minimal
Note that the Stars, Official and Automated descriptors are only avail-
able on Docker Hub and are hence not displayed by default.
$ podman search --format "{{.Name}}\t{{.Stars}}\t{{.Official}}" alpine --limit 3
docker.io/library/alpine 7956 [OK]
docker.io/alpine/git 192
docker.io/anapsix/alpine-java 474
quay.io/libpod/alpine 0
quay.io/vqcomms/alpine-tools 0
quay.io/wire/alpine-deps 0
Search and list tags for the specified image returning the first four
images from each defined registry.
$ podman search --list-tags registry.access.redhat.com/ubi8 --limit 4
NAME TAG
registry.access.redhat.com/ubi8 8.4-211
registry.access.redhat.com/ubi8 8.4-206.1626828523-source
registry.access.redhat.com/ubi8 8.4-199
registry.access.redhat.com/ubi8 8.4-211-source
Note: This works only with registries that implement the v2 API. If
tried with a v1 registry an error is returned.
FILES
registries.conf (/etc/containers/registries.conf)
registries.conf is the configuration file which specifies which con-
tainer registries is consulted when completing image names which do not
include a registry or domain portion.
SEE ALSO
podman(1), containers-registries(5)
HISTORY
January 2018, Originally compiled by Urvashi Mohnani umohnani@redhat.com
⟨mailto:umohnani@redhat.com⟩
podman-search(1)
Generated by dwww version 1.16 on Tue Dec 16 06:02:41 CET 2025.