Skip to main content

Pulling podman images from a container repository

Check out podman's new container image pulling options.
Pulling podman images

Image by Amanda McConnell from Pixabay

There are many new changes and additions that have happened to the pull functionality in the podman build command. As of Podman version 1.7.0, which was released in January 2020, the ways that you can pull and how you pull container images during podman build have been changed and added to. Let's dive in.

Prior to Podman v1.17

In earlier versions of podman build, there were three different ways to pull a container image as part of the build process. The options were the default --pull=true, --pull=false, or --pull-always. When --pull=true (or just --pull) was used, the container image would be pulled from the repository if the image was not present in local storage. This approach differed from the docker build --pull functionality as Docker pulls the image if it's not in local storage or if there's a different version in the repository. Needless to say, this caused some confusion.

Then for the podman build --pull=false functionality, the container image was never pulled, even if the image was not present in local storage, thus the podman build command would fail. This behavior caused more confusion as the docker build --pull=false command would pull the image if and only if it was not present in the local storage, and it wouldn't error unless the image was not present either locally or in the repository.

Finally, Podman had the unique --pull-always option, which did not care about any current status. It always pulled the container image regardless of what was in local storage, or if the image had or had not changed in the repository.

So what's changed?

First of all, nothing has changed with the --pull-always option. That's still your tool to always pull the image. However, the --pull=true and the --pull=false options for the podman build command now emulate the behavior of their counterparts in Docker.

The podman build --pull=true command will pull the container image from the repository if it is not in local storage or if the version in the repository is different from the one in local storage. Likewise, podman build --pull=false now pulls the container image only if it is not present in the local storage. Now the behavior for these two options matches the Docker functionality.

But wait, what happens if you like the old podman build --pull=false functionality? Sometimes it might be handy to never pull a container image. The functionality is still in podman build using the new --pull-never option. If you do a podman build --pull-never command, the command uses only the image in the local storage and raises an error if it's not present.

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

Pull flavor of the day

So many options for pull can make your head spin! They all have their uses, and it's worth quickly mentioning that if a layer is already present, the pull options will all reuse the local layer. Now let's take a look at each of the options.


If you want to make sure you have the latest container image from the repository, then the --pull-always command is for you. It attempts to pull the image from the repository, and it fails if the image is not there, even if the image is in the local storage already. This option still reuses the local layers if they are the same as the ones in the repository. Due to the checking over the network that this option does, it's generally the slowest.


The default --pull option has the same result as --pull-always. The difference is that the container image in the local storage will be used by this option if the image matches the one in the repository. Also, if the image is stored locally, but it is not in the repository, it does not throw an error. This option instead uses the locally-stored image. Using this option ensures you have the latest version of the image and favors using the local image if it is available.


To lessen your network traffic further, you can use the --pull=false option. This option guarantees that you won't refresh the container image in your local repository if you like how it's currently set up. If you don't want to hit the network, you can choose not to by using this option. However, if that image is removed from local storage, then --pull=false will pull the image for you from the repository.


Finally, the --pull-never option is a really good option to use if you're very concerned about the contents of your container image. You want to be 100% certain that someone doesn't put an infected image in the repository that you then pull down. When this option is used, it only uses the vetted container image in your local storage and throws an error if it is not found.

To pull or not to pull?

Using the default --pull=true option with podman build is the correct choice for most sysadmins. Unless the container image changes on the repository, you won't take the cost of the network pulling when you use the image. If it does change, then you'll get the latest copy. If you're a "get it and set it" type of person, then --pull=false is probably best. You'll only suffer the cost of the network pull one time, then can quickly get into the business of building.

However, if you have a lot of security concerns and want to make ultra sure that your container image is the image you expect it to be and that it's free of any viral infection, then the --pull-never option is the one for you. Once you get your image cleaned, inspected, and then stored in your local storage, you can use it with utmost confidence that it won't change out from underneath you during your next build process.

Last words

The new and updated --pull options that now come with the podman build command let you decide what's best for your environment. You can balance the need between the most up to date container image, faster builds, and ultra-safe container images. It all depends on what works best for your environment. Pulling in Podman really is a wonderful thing with these new and improved pull options!

[ Ready to get started? Start using containers for free. ]

Topics:   Containers   Podman  
Author’s photo

Tom Sweeney

Software engineer at Red Hat working on containers focusing on the Buildah and Podman projects. Manages the and websites and can be found on freenode at #buildah and #podman. More about me

Try Red Hat Enterprise Linux

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