Getting Started

In the pages here we will first review some important concepts about the Singularity Registry Global Client, and then provide install instructions and tutorials for using the client, both on the command line and from within Python.

How does Singularity Global Client relate to Singularity?

With Singularity, you can pull images from Singularity Hub, or assemble Docker layers into an image with any of the action commands like run, exec, etc. The Singularity client is ideal for creating and using images. The Singularity Global Client specializes in one particular thing - movement of images. This maps nicely only the “singularity pull” functionality, and there is both overlap and some key differences.


We want the sregistry client to support the current workflow of using Singularity images. This means that the local file database created sregistry lives alongside the cache folders:

tree -L 1 $HOME/.singularity
├── docker
├── shub
└── sregistry.db

It also means that when you interact with a storage endpoint using Singularity registry, it will honor your Singularity cache folder. This means that if you use sregistry to manage images, when you run Singularity proper those images will be found.


You can best think of the sregistry client as an extension to Singularity, one that adds a layer of organization to images that live on your system. It fits the niche of the local user, whether on his personal machine or home node on a cluster, to be able to move images between common places, search, and generally manage them. A few additional keys points:

It’s entirely up to you how you want to (or don’t want to) use sregistry clients. If you have a preference for a particular kind of storage, this will be very useful to you. If you want to integrate Singularity into your own software, this will also be useful.


When you start a client, whether it be in an interactive python environment or running natively on your host or via a Singularity container, a client for an endpoint of choice is started up, and this client will give you access, minimally, to a core set of commands:

let you do any or a subset of the following:


The following commands are considered “local” in that they come with every client, and are specifically created to interact with your local registry (the database and storage). If you disable the database and storage, then you will logically not have these commands.

These specific commands are demonstrated with more examples.

Client (remote)

This next set of commands, while they interact with local resources, are primarily implemented by the specific clients. For example, a pull from Singularity Hub is going to have particular commands using the Singularity Hub API.

Each of these commands will be detailed with examples in the various client walkthroughs, and if you are implementing an endpoint, there are also details about how you should “fill in the space” to implement your custom client.


By default, using sregistry will help you manage a local database of images for personal use. This is an sqlite3 database, so you should not use it for scaled write operations - you would use sregistry to push pull, search, and then run scaled operations with singularity proper with the path from sregistry. If you need to manage images at scale, you should consider hosting a Singularity Registry or building on Singularity Hub.


The database itself stores metadata and paths for images. You can imagine pulling an image, perhaps that looks like this:

sregistry pull shub://vsoch/hello-world

and then you would want to be able to search your local database, and find the image.

sregistry search vsoch/hello-world

On the back end, this means that we are storing (minimally) some path, and metadata about the image. But where does the image actually live?


The sregistry client is driven by environment variables. Since each call is quick, you can have a lot of power to switch between endpoints and clients just by way of changing an environment variable for the call. Here we review the most important defaults, and then a robust list of all that you can set.


Each client might have slight variability in the functions that it supports. For example, you can push to a Singularity Registry that you have credentials for, but you can’t push to Singularity Hub directly. We will discuss clients at a high level here. When you use the client, whether from within Python or command line:

  1. The environment is parsed for SREGISTRY_CLIENT. If it’s found, then you have specified a particular client to use and that choice is honored.
  2. We look for an activated client name in SREGISTRY_CLIENT_SECRETS.
  3. If a specified client is not declared, then we step through looking for client-specific exports. Finding a path to a SREGISTRY_CLIENT_SECRETS for example means it is likely you want to interact with a Singularity Registry, so the client is loaded.
  4. If no environment variables can be determined, the default client is optimized to work with Singularity Hub.

In all cases, after we create a client, given that we have not disabled it, a local database is generated or connected to:

from sregistry.main import get_client
client = get_client()
# Database: /home/vanessa/.singularity/sregistry.db

And following this step, operations that we do across all clients interact with our local database.


An endpoint is a remote place to put or get images. It could be Singularity Hub (pulling images from Google Cloud Storage), Dropbox (saving and retrieving images from a personal Dropbox) or Globus (moving images to and from endpoints that you control). You might even host one of these endpoints locally, so for the purposes of the client, just remember that it will interact with both your hosted endpoints and others (with appropriate permissions).


The most tested approach has been to install sregistry in your local python using pip, or from Github:

pip install sregistry
git clone
cd sregistry-cli
python install

If you need to install dependencies for a particular client, just provide the name:

pip install -e .[google-storage]


Now that we’ve discussed these concepts, let’s jump into using the client. We have two getting started guides:

Once you’ve mastered the basics, take a look at the specific clients documentation