RUN-SINGULARITY(1)

NAME
run-singularity - launch a Singularity containers with a runscript

DESCRIPTION
USAGE: singularity [...] run [run options...] <container path> [...]

This command will launch a Singularity container and execute a runscript if one is defined for that container. The runscript is a file at '/singularity'. If this file is present (and executable) then this command will execute that file within the container automatically. All arguments following the container name will be passed directly to the runscript.

  RUN OPTIONS:

-a|--app
    Run an app's runscript instead of the default one

-B|--bind <spec>
    A user-bind path specification. spec has the format src[:dest[:opts]], where src and dest are outside and inside paths. If dest is not given, it is set equal to src. Mount options ('opts') may be specified as 'ro' (read-only) or 'rw' (read/write, which is the default). This option can be called multiple times.

-c|--contain
    Use minimal /dev and empty other directories (e.g. /tmp and $HOME) instead of sharing filesystems on your host

-C|--containall
    Contain not only file systems, but also PID and IPC

-e|--cleanenv
    Clean environment before running container

-H|--home <spec>
    A home directory specification. spec can either be a src path or src:dest pair. src is the source path of the home directory outside the container and dest overrides the home directory within the container

-i|--ipc
    Run container in a new IPC namespace

-n|--net
    Run container in a new network namespace (loopback is only network device active)

--nv
    Enable experimental Nvidia support

-o|--overlay
    Use a persistent overlayFS via a writable image

-p|--pid
    Run container in a new PID namespace

--pwd
    Initial working directory for payload process inside the container

-S|--scratch <path> Include a scratch directory within the container that
    is linked to a temporary dir (use -W to force location)

-u|--userns
    Run container in a new user namespace (this allows Singularity to run completely unprivileged on recent kernels and doesn't support all features)

-W|--workdir
    Working directory to be used for /tmp, /var/tmp and $HOME (if -c/--contain was also used)

-w|--writable
    By default all Singularity containers are available as read only. This option makes the file system accessible as read/write.

  CONTAINER FORMATS SUPPORTED:

*.sqsh
    SquashFS format. Native to Singularity 2.4+

*.img
    This is the native Singularity image format for all Singularity versions < 2.4.

*.tar*
    Tar archives are exploded to a temporary directory and run within that directory (and cleaned up after). The contents of the archive is a root file system with root being in the current directory. Compression suffixes as '.gz' and '.bz2' are supported.

directory/
    Container directories that contain a valid root file system.

instance://*
    A local running instance of a container. (See the instance command group.)

shub://*
    A container hosted on Singularity Hub

docker://*
    A container hosted on Docker Hub

EXAMPLES:

    # Here we see that the runscript prints "Hello world: " $ singularity exec /tmp/Debian.img cat /singularity #!/bin/sh echo "Hello world: "

    # It runs with our inputs when we run the image $ singularity run /tmp/Debian.img one two three Hello world: one two three

    # Note that this does the same thing $ ./tmp/Debian.img one two three

For additional help, please visit our public documentation pages which are found at:

    http://singularity.lbl.gov/