Singularity Pull

These docs are for Singularity Version 2.5.1. For older versions, see our archive

Singularity pull is the command that you would want to use to communicate with a container registry. The command does exactly as it says - there exists an image external to my host, and I want to pull it here. We currently support pull for both Docker and Singularity Hub images, and will review usage for both.

Singularity Hub

Singularity differs from Docker in that we serve entire images, as opposed to layers. This means that pulling a Singularity Hub means downloading the entire (compressed) container file, and then having it extract on your local machine. The basic command is the following:

How do tags work?

On Singularity Hub, a tag coincide with a branch. So if you have a repo called vsoch/hello-world, by default the file called Singularity (your build recipe file) will be looked for in the base of the master branch. The command that we issued above would be equivalent to doing:

singularity pull shub://vsoch/hello-world:master

To enable other branches to build, they must be turned on in your collection (more details are available in the Singularity Hub docs). If you then put another Singularity file in a branch called development, you would pull it as follows:

singularity pull shub://vsoch/hello-world:development

The term latest in Singularity Hub will pull, across all of your branches, the most recent image. If development is more recent than master, it would be pulled, for example.

Image Names

As you can see, since we didn’t specify anything special, the default naming convention is to use the username, reponame, and the branch (tag). You have three options for changing this:

Custom Name

Name by commit

Each container build on Singularity Hub is associated with the GitHub commit of the repo that was used to build it. You can specify to name your container based on the commit with the --commit flag, if, for example, you want to match containers to their build files:

Pull to different folder

For any of the above, if you want to specify a different folder for your image, you can define the variable SINGULARITY_PULLFOLDER. By default, we will first check if you have the SINGULARITY_CACHEDIR defined, and pull images there. If not, we look for SINGULARITY_PULLFOLDER. If neither of these are defined, the image is pulled to the present working directory, as we showed above. Here is an example of pulling to /tmp.

this is because the same logic is happening on the back end. Thus, the pull command with a docker uri also supports arguments --size and --name Here is how I would pull an ubuntu image, but make it bigger, and name it something else.