podman-search(1)

🎀 podman-search(1) 🎀

hii bestie, welcome to the podman-search(1) page from the General Commands Manual 💖 it's short, it's sweet, it finds images for you, and by the end of this you're gonna be searching registries like it's nothing. let's go 🦋

---

✨ NAME ✨

podman-search — search a registry for an image 🔍

---

🌸 SYNOPSIS 🌸

podman search [options] term

---

💜 DESCRIPTION 💜

okay so podman search goes and searches a registry — or a whole list of registries — for an image that matches what you're looking for. and the way you tell it which registry you want? you just prefix the registry right into the search term, like registry.fedoraproject.org/fedora ✨ easy. if you don't do that, it uses all the unqualified-search registries listed in containers-registries.conf(5) by default.

the default number of results is 25 — iconic number — and you can limit it with the --limit flag. heads up though: if more than one registry is being searched, that limit gets applied to each registry, not to the grand total. you can also filter the output with the --filter flag. and if you want everything available in a registry with no specific search term at all, just type the registry name with a trailing / and vibe — like registry.fedoraproject.org/ 🫶

now for the real talk, bestie: 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, so it's giving "every registry does its own thing." some registries may not support searching at all 😭 and searching without a search term only works for registries that implement the v2 API. no cap.

also, here are the invocation shapes you'll see floating around:

podman [GLOBAL OPTIONS]

podman search [GLOBAL OPTIONS]

podman search [OPTIONS] TERM

---

💅 OPTIONS 💅

• --authfile=path — the path to the authentication file. default is ${XDG_RUNTIME_DIR}/containers/auth.json on Linux, and $HOME/.config/containers/auth.json on Windows/macOS. this file is created by podman login. and if the authorization state isn't found there, it checks $HOME/.docker/config.json, which is set using docker login 👑

also note: you can override the default path of the authentication file by setting the REGISTRY_AUTH_FILE environment variable. do it like this: export REGISTRY_AUTH_FILE=path.

• --cert-dir=path — use the certificates at path (*.crt, *.cert, *.key) to connect to the registry. (default: /etc/containers/certs.d) for the deets, see containers-certs.d(5). ⚠️ heads up: this option is not available with the remote Podman client, including Mac and Windows machines (excluding WSL2 ones).
• --compatible — after the name and the description, it also shows the stars, official and automated descriptors, exactly the way Docker does. Podman doesn't show these by default because most public container registries just don't support them 🙈
• --creds=[username[:password]] — the [username[:password]] to use to authenticate with the registry, if required. if one or both values aren't supplied, a command line prompt pops up and you can enter the value. the password is entered without echo 🤫

note that the credentials you specify 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)) — for those, consider using a containers-auth.json(5) file instead.

• --filter, -f=filter — filter the 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:

• .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 registries 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 results.
• --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 (default: true). if explicitly set to true, TLS verification is used. if set to false, TLS verification is not used. if not specified, TLS verification 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
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 available 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 you try it with a v1 registry, an error is returned 💀

---

🍓 FILES 🍓

• registries.conf (/etc/containers/registries.conf)

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 🗂️

---

🦋 SEE ALSO 🦋

podman(1), containers-registries(5)

---

👑 HISTORY 👑

January 2018, originally compiled by Urvashi Mohnani umohnani@redhat.com <mailto:umohnani@redhat.com> 💌

---

and that's the whole page bestie, you ate that 🫶 this was podman-search(1) from the General Commands Manual, and if you ever need to find it again it's filed under that exact same name, periodt 💅✨🌈