Chapter 3. Working with container registries

download PDF

A container image registry is a repository or collection of repositories for storing container images and container-based application artifacts. The /etc/containers/registries.conf file is a system-wide configuration file containing the container image registries that can be used by the various container tools such as Podman, Buildah, and Skopeo.

If the container image given to a container tool is not fully qualified, then the container tool references the registries.conf file. Within the registries.conf file, you can specify aliases for short names, granting administrators full control over where images are pulled from when not fully qualified. For example, the podman pull command pulls a container image from the registry to your local system as specified in the registries.conf file.

3.1. Container registries

A container registry is a repository or collection of repositories for storing container images and container-based application artifacts. The registries that Red Hat provides are:

  • (requires authentication)
  • (requires no authentication)
  • (holds Red Hat Partner Connect program images)

To get container images from a remote registry, such as Red Hat’s own container registry, and add them to your local system, use the podman pull command:

# podman pull <registry>[:<port>]/[<namespace>/]<name>:<tag>

where <registry>[:<port>]/[<namespace>/]<name>:<tag> is the name of the container image.

For example, the container image is identified by:

  • Registry server (
  • Namespace (ubi9)
  • Image name (ubi)

If there are multiple versions of the same image, add a tag to explicitly specify the image name. By default, Podman uses the :latest tag, for example ubi9/ubi:latest.

Some registries also use <namespace> to distinguish between images with the same <name> owned by different users or organizations. For example:

NamespaceExamples (<namespace>/<name>)


redhat/kubernetes, google/kubernetes

login (user name)

alice/application, bob/application


devel/database, test/database, prod/database

For details on the transition to, see Red Hat Container Registry Authentication. Before you can pull containers from, you need to authenticate using your RHEL Subscription credentials.

3.2. Configuring container registries

You can display the container registries using the podman info --format command:

$ podman info -f json | jq '.registries["search"]'

The podman info command is available in Podman 4.0.0 or later.

You can edit the list of container registries in the registries.conf configuration file. As a root user, edit the /etc/containers/registries.conf file to change the default system-wide search settings.

As a user, create the $HOME/.config/containers/registries.conf file to override the system-wide settings.

unqualified-search-registries = ["", "", ""]
short-name-mode = "enforcing"

By default, the podman pull and podman search commands search for container images from registries listed in the unqualified-search-registries list in the given order.

Configuring a local container registry

You can configure a local container registry without the TLS verification. You have two options on how to disable TLS verification. First, you can use the --tls-verify=false option in Podman. Second, you can set insecure=true in the registries.conf file:

Blocking a registry, namespace, or image

You can define registries the local system is not allowed to access. You can block a specific registry by setting blocked=true.

location = ""
blocked = true

You can also block a namespace by setting the prefix to prefix="". For example, pulling the image using the podman pull registry. command will be blocked, because the specified prefix is matched.

location = ""
blocked = true

prefix is optional, default value is the same as the location value.

You can block a specific image by setting prefix="".

location = ""
blocked = true
Mirroring registries

You can set a registry mirror in cases you cannot access the original registry. For example, you cannot connect to the internet, because you work in a highly-sensitive environment. You can specify multiple mirrors that are contacted in the specified order. For example, when you run podman pull command, the is tried first, then


Additional resources

3.3. Searching for container images

Using the podman search command you can search selected container registries for images. You can also search for images in the Red Hat Container Catalog. The Red Hat Container Registry includes the image description, contents, health index, and other information.


The podman search command is not a reliable way to determine the presence or existence of an image. The podman 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. Searching without a search term only works for registries that implement the v2 API. The same holds for the docker search command.

To search for the postgresql-10 images in the registry, follow the steps.


  • The container-tools meta-package is installed.
  • The registry is configured.


  1. Authenticate to the registry:

    # podman login
  2. Search for the image:

    • To search for a particular image on a specific registry, enter:

      # podman search
      INDEX       NAME                                           DESCRIPTION           STARS   OFFICIAL   AUTOMATED         This container image ...  0   PostgreSQL is an  ...     0
    • Alternatively, to display all images provided by a particular registry, enter:

      # podman search
    • To search for the image name in all registries, enter:

      # podman search postgresql-10

      To display the full descriptions, pass the --no-trunc option to the command.

Additional resources

  • podman-search man page

3.4. Pulling images from registries

Use the podman pull command to get the image to your local system.


  • The container-tools meta-package is installed.


  1. Log in to the registry:

    $ podman login
    Username: <username>
    Password: <password>
    Login Succeeded!
  2. Pull the container image:

    $ podman pull

Verification steps

  • List all images pulled to your local system:

    $ podman images
    REPOSITORY                           TAG     IMAGE ID      CREATED      SIZE          latest  3269c37eae33  7 weeks ago  208 MB

Additional resources

  • podman-pull man page

3.5. Configuring short-name aliases

Red Hat recommends always to pull an image by its fully-qualified name. However, it is customary to pull images by short names. For example, you can use ubi9 instead of

The registries.conf file allows to specify aliases for short names, giving administrators full control over where images are pulled from. Aliases are specified in the [aliases] table in the form "name" = "value". You can see the lists of aliases in the /etc/containers/registries.conf.d directory. Red Hat ships a set of aliases in this directory. For example, podman pull ubi9 directly resolves to the right image, that is

For example:

unqualified-search-registries=["", “"]


The short-names modes are:

  • enforcing: If no matching alias is found during the image pull, Podman prompts the user to choose one of the unqualified-search registries. If the selected image is pulled successfully, Podman automatically records a new short-name alias in the $HOME/.cache/containers/short-name-aliases.conf file (rootless user) or in the /var/cache/containers/short-name-aliases.conf (root user). If the user cannot be prompted (for example, stdin or stdout are not a TTY), Podman fails. Note that the short-name-aliases.conf file has precedence over the registries.conf file if both specify the same alias.
  • permissive: Similar to enforcing mode, but Podman does not fail if the user cannot be prompted. Instead, Podman searches in all unqualified-search registries in the given order. Note that no alias is recorded.
  • disabled: All unqualified-search registries are tried in a given order, no alias is recorded.

Red Hat recommends using fully qualified image names including registry, namespace, image name, and tag. When using short names, there is always an inherent risk of spoofing. Add registries that are trusted, that is, registries that do not allow unknown or anonymous users to create accounts with arbitrary names. For example, a user wants to pull the example container image from registry. If is not first in the search list, an attacker could place a different example image at a registry earlier in the search list. The user would accidentally pull and run the attacker image rather than the intended content.

Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.