Skip to main content

Container image short names in Podman

This new feature, pulling images with Podman by using short names, includes more security, greater convenience, and is another step forward for container management.
Colorful spice containers

Image by monicore from Pixabay

When people approach me to talk about Podman and containers, I usually ask if they are familiar with Docker. Most people are, and the conversations quickly move beyond the fact that Podman can act as a drop-in replacement for Docker. In fact, there are many useful and innovative features that make Podman special. Podman has excellent rootless support, it can generate systemd unit files for easily containerizing systemd services, and it has a powerful RESTful API that allows for running Podman on macOS and Windows. Those are just a few of the great features.

Some commands that Podman inherited from Docker were enhanced to make them more useful to a broader audience. The podman image remove command, for instance, received a --all flag to remove all images and not only one.

Pulling images by short name

Another useful enhancement was to pull container images. Pulling a container image boils down to talking to an HTTP server (i.e., a container registry) in a specific protocol that is written down in the OCI distribution specification. But we humans are lazy and writing down the entire URI of a container image, including the server, maybe the port, the optional repository, and the name followed by a tag or digest is not convenient at all. That is why Docker defaults to pulling from a specific registry (i.e., when a reference to an image does not explicitly include a registry. So if we attempt to docker pull fedora, the specified image name is completed for us, and we will actually pull

To allow for an easy transition from Docker, Podman supports auto-completing image names as well, but we did not want to lock-in our users to just one registry as Docker does. There are many on-premise, public, and commercial container registries out there, such as, GitHub Container Registry, or Amazon Elastic Container Registry.

[ You might also enjoy: Tick-tock. Does your container know what time it is? ]

Hence, Podman allows sysadmins to specify a list of container registries to auto-complete short-image names. Podman then reaches out to each registry in the given order and attempts to pull the specified image until it has been pulled successfully.

We can specify these search registries in the registries.conf configuration file. So let's assume we have a registries.conf file that sets the unqualified-search-registries field to followed by If we now do a podman pull repo/image:latest, Podman will find out that repo/image:latest does not include a server, so it must be completed. Podman would first attempt to pull and move on to if the image was not present on

The risk of using short names

This flexibility in completing short-image names is used in many Linux distributions to support more than just Fedora, for instance, puts as the first search registry so that a podman pull fedora will always pull from the official registry of the Fedora community. Podman prints the search process to make it more obvious to users what's going on.

Let's have a look at another image and run podman pull nginx on a fresh Fedora 33 system:

Screenshot of "podman pull nginx" command results.

We can see that Podman contacts the configured search registries in order as specified in /etc/containers/registries.conf until an image has been pulled successfully.

While the short-image completion is widely used and a highly demanded feature by our users and customers, it can also be exploited. Let's take the initial example of pulling repo/image:latest from and Although we may intend pulling, we could get instead. Pulling the wrong image can have all kinds of undesired consequences, such as service downtimes, malfunctions, or even a security threat. As reported earlier this year, an attacker may squat and place malicious images there to trick and attack users.

Due to the inherent ambiguity when pulling short-image names, we always recommend to fully specify an image's source. For instance, rather than fedora. On the other hand, we also acknowledge the convenience of using short names, so we developed a secure way of using short names that eliminates the risk of pulling images from untrusted sources.

Short-name aliasing

To secure using short names, we are introducing so-called short-name aliases. Similar to aliases in BASH, a short-name alias has a left-hand name that is being replaced with a right-hand value. Short-name aliases can now be configured in the registries.conf file as follows:

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



All aliases must be specified in the new aliases table. Using the above registries.conf file, Podman will resolve fedora immediately and securely to It will not try resolving fedora by using the registries listed in the unqualified-search-registries field.

Given this example, you would not pull if it existed, only the image specified by the alias,

We are currently assembling a public list of short-name aliases that can be used across the community. Multiple Linux distributions and companies have expressed interest in collaborating with the Podman maintainers on assembling the short-name list, which we maintain on

But what happens now when we attempt to pull by short name and do not have a matching alias?

Results of "podman pull fedora" command with prompt to select an image

If no matching alias is found, Podman will now prompt the user to choose one of the unqualified-search registries. If the selected image is pulled successfully, Podman will automatically record a new short-name alias in the users $HOME/.config/containers/short-name-aliases.conf file. Subsequent pull attempts will use these aliases to resolve the previously selected and pulled image, even if it is removed. Note that the short-name-aliases.conf has precedence over registries.conf if both specify the same alias.

Once a short-name alias is recorded, we won't be prompted any more, and Podman will correctly auto-complete the short name:

Results of "podman pull fedora" after the registry is recognized.

Note that a short-name alias is only recorded if the selected image was pulled successfully. If we accidentally select the wrong image, the pull would fail. We might also just kill a pull operation with CTRL+C.

What happens if I run Podman in a script and cannot be prompted?

That is a particularly delicate issue. Security should always be on by default and not be opt-in. We also need to account for the millions of Podman deployments that must continue working even after an update. Taking everything into account, we came up with three so-called "short-name modes" that can be configured in the registries.conf:

  • enforcing: If no alias is found and more than one unqualified-search registry is set, prompt the user to select one registry to pull from. If the user cannot be prompted (i.e., stdin or stdout are not a TTY), Podman will throw an error.
  • permissive: Behaves as enforcing but will not throw an error if the user cannot be prompted. Instead, Podman will try all unqualified-search registries in the given order. Note that no alias will be recorded.
  • disabled: Podman will try all unqualified-search registries in the given order, and no alias will be recorded. This is pretty much the same behavior of Podman before short names were introduced.

These three modes meet all our requirements. On new installations, the short-name mode in the registries.conf file will be set to enforcing. This way, new installations are as secure as possible. On existing systems, however, the registries.conf files will not be altered, and Podman will default to the permissive mode. This way, updated systems are secure when running interactively while not breaking existing deployments.

Note that distributions have full control over which mode they want to set by default on new installations. For now, Fedora and Red Hat Enterprise Linux will default to permissive.  Future versions may default to enforcing.

When will short-name aliasing be shipped?

The short-name aliasing feature will be shipped as a tech preview with Podman 2.2. Users can try it out by setting the CONTAINERS_SHORT_NAME_ALIASING environment variable to on. After collecting initial feedback from the community, short-name aliasing will be enabled with Podman 3.0, which is expected in early 2021.

If you want to permanently opt-into using short-name aliasing, you can configure the containers.conf as follows:



Do Buildah, Skopeo, and CRI-O support short-name aliasing?

Buildah behaves exactly as Podman does and should ship short-name aliasing as a tech preview with Buildah 1.18. As with Podman, users can try out the aliasing feature by setting the CONTAINERS_SHORT_NAME_ALIASING environment variable to on. Short-name aliasing will be enabled with Buildah 2.0, which is expected in early 2021.

CRI-O will also gain support for short-name aliasing, but since CRI-O is a daemon, it can not prompt and will only use predefined aliases.

Skopeo has never been subject to the aforementioned risk when using short names. Any short name reference will be completed to Hence, Skopeo does not support short-name aliasing.

[ Getting started with containers? Check out this free course. Deploying containerized applications: A technical overview. ]


Short-name aliasing improves security and accuracy when pulling images while continuing the user-friendly feature of less typing. Through prompting, users will have more control over the images they pull, and distributions will have more ownership of their images.

Topics:   Containers   Podman  
Author’s photo

Valentin Rothberg

Container engineer at Red Hat, bass player, music lover. More about me

Try Red Hat Enterprise Linux

Download it at no charge from the Red Hat Developer program.