The Pull Command

The Apptainer command for pulling an image takes the following format.

At the end of the command, you always need to specify the URI, which is the location of the image you want to pull. The result of this command will be a SIF file downloaded to your directory. Apptainer will give it a default name, but if you want to give it a particular name, you can specify that immediately before the URI.

Note that when you pull an image, it will be placed in the current working directory. At TACC, you may want to create a folder in the $SCRATCH file system just for your container images and cd into it first. That way, you won't end up with a jumble of files, and you will avoid running containers from your home directory.

Also, before you begin to work with Apptainer containers on TACC Vista (e.g.), you should first start an interactive session on a development node and load the tacc-apptainer environment module:

Pulling from Docker/OCI Registries

In the following example, we pull a container image called lolcow from the main Docker Hub registry. Because this is a Docker/OCI image, the pull involves a conversion process, with the result being a SIF file. If no tag is specified, the latest version is retrieved, and Apptainer inserts _latest into the name of the stored file for full identification.

Next, we pull a similar Docker container image having the same name, lolcow, from the GitHub Container Repository (ghcr.io), which is a popular alternative to Docker Hub. Since our current directory already has a lolcow_latest.sif file, it is necessary to give the new image file a custom name through the --name option.

Note that the container image in this example will not work properly on Vista because the URI does not include a build for the ARM64 archtecture. For more details on what happens when the URI does not provide a build for the host's architecture, see Images Built for Different Architectures.

Just because we pulled an image from the "apptainer" namespace at GHCR, it does not imply that the original image uses Apptainer's native SIF format. In fact, the original image uses the Docker/OCI format, just like any container image whose URI starts with docker://. Therefore, the above pull again involves a conversion process, with the result being a SIF file with the custom name.

But GHCR has no inherent preference for Docker/OCI images. SIF files can be found there as well. When you issue a pull command, you can either pull a Docker/OCI image via the docker:// prefix, or a SIF file via the oras:// prefix, depending on what is available.

Finally, the GitHub Container Registry is not a separate service from GitHub itself. Rather, it is integrated into GitHub's broader set of repository services. For that reason, there is no global directory or search engine for the ghcr.io registry. To locate a particular image, you will need to know at least the username or the organization name of the provider. By visiting the provider's profile page on GitHub, you can view their available container images by selecting the "Packages" tab, then the "Containers" type in that tab.

Pulling from Singularity and Apptainer Registries

The library:// URI prefix signifies a native Singularity or Apptainer registry. When you pull an image from a library:// URI, Apptainer assumes it is stored in SIF format and simply downloads the file for you; otherwise, the pull fails. The same is true of a URI starting with oras://, because a registry of that type stores simple artifacts like .sif files.

You can confirm this behavior by pulling yet another lolcow container image, this time from Singularity Container Services, which is the registry that TACC has chosen as the default for the library:// URI prefix. Because the remote lolcow image is already a SIF file, you should observe that there is no output from a conversion process, unlike what we saw in the previous cases.