.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.49.3.
.TH RUN-SINGULARITY "1" "April 2024" "run-singularity 4.1.2+ds1-1" "User Commands"
.SH NAME
run-singularity \- launch a Singularity containers with a runscript
.SH DESCRIPTION
Run the user\-defined default command within a container
.SS "Usage:"
.IP
singularity run [run options...] <container>
.SS "Description:"
.IP
This command will launch a Singularity container and execute a runscript
if one is defined for that container. The runscript is a metadata file within
the container that contains shell commands. If the 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.
.IP
singularity run accepts the following container formats:
.TP
*.sif
Singularity Image Format (SIF). Native to Singularity 3.0+
.TP
*.sqsh
SquashFS format.  Native to Singularity 2.4+
.TP
*.img
ext3 format. Native to Singularity versions < 2.4.
.TP
directory/
sandbox format. Directory containing a valid root file
system and optionally Singularity meta\-data.
.TP
instance://*
A local running instance of a container. (See the instance
command group.)
.TP
library://*
A SIF container hosted on a Library
(default https://cloud.sylabs.io/library)
.TP
docker://*
A Docker/OCI container hosted on Docker Hub or another
OCI registry.
.TP
shub://*
A container hosted on Singularity Hub.
.TP
oras://*
A SIF container hosted on an OCI registry that supports
the OCI Registry As Storage (ORAS) specification.
.SH OPTIONS
.TP
\fB\-\-add\-caps\fR string
a comma separated capability list to add
.TP
\fB\-\-allow\-setuid\fR
allow setuid binaries in container
(root only)
.TP
\fB\-\-app\fR string
set an application to run inside a
container
.TP
\fB\-\-apply\-cgroups\fR string
apply cgroups from file for
container processes (root only)
.TP
\fB\-\-authfile\fR string
Docker\-style authentication file to
use for writing/reading OCI registry
credentials
.TP
\fB\-B\fR, \fB\-\-bind\fR strings
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).
Multiple bind paths can be given by
a comma separated list.
.TP
\fB\-\-blkio\-weight\fR int
Block IO relative weight in range
10\-1000, 0 to disable
.TP
\fB\-\-blkio\-weight\-device\fR strings
Device specific block IO relative weight
.TP
\fB\-\-cdi\-dirs\fR strings
comma\-separated list of directories
in which CDI should look for device
definition JSON files. If omitted,
default will be: \fI\,/etc/cdi\/\fP,/var/run/cdi
.TP
\fB\-e\fR, \fB\-\-cleanenv\fR
clean environment before running
container
.TP
\fB\-\-compat\fR
apply settings for increased
OCI/Docker compatibility. Infers
\fB\-\-containall\fR, \fB\-\-no\-init\fR, \fB\-\-no\-umask\fR,
\fB\-\-no\-eval\fR, \fB\-\-writable\-tmpfs\fR.
.TP
\fB\-c\fR, \fB\-\-contain\fR
use minimal \fI\,/dev\/\fP and empty other
directories (e.g. \fI\,/tmp\/\fP and $HOME)
instead of sharing filesystems from
your host
.TP
\fB\-C\fR, \fB\-\-containall\fR
contain not only file systems, but
also PID, IPC, and environment
.TP
\fB\-\-cpu\-shares\fR int
CPU shares for container (default \fB\-1\fR)
.TP
\fB\-\-cpus\fR string
Number of CPUs available to container
.TP
\fB\-\-cpuset\-cpus\fR string
List of host CPUs available to container
.TP
\fB\-\-cpuset\-mems\fR string
List of host memory nodes available
to container
.TP
\fB\-\-cwd\fR string
initial working directory for
payload process inside the container
(synonym for \fB\-\-pwd\fR)
.TP
\fB\-\-device\fR strings
fully\-qualified CDI device name(s).
A fully\-qualified CDI device name
consists of a VENDOR, CLASS, and
NAME, which are combined as follows:
<VENDOR>/<CLASS>=<NAME> (e.g.
vendor.com/device=mydevice).
Multiple fully\-qualified CDI device
names can be given as a comma
separated list.
.TP
\fB\-\-disable\-cache\fR
dont use cache, and dont create cache
.TP
\fB\-\-dns\fR string
list of DNS server separated by
commas to add in resolv.conf
.TP
\fB\-\-docker\-host\fR string
specify a custom Docker daemon host
.TP
\fB\-\-docker\-login\fR
login to a Docker Repository
interactively
.TP
\fB\-\-drop\-caps\fR string
a comma separated capability list to drop
.TP
\fB\-\-env\fR stringToString
pass environment variable to
contained process (default [])
.TP
\fB\-\-env\-file\fR string
pass environment variables from file
to contained process
.TP
\fB\-f\fR, \fB\-\-fakeroot\fR
run container in new user namespace
as uid 0
.TP
\fB\-\-fusemount\fR strings
A FUSE filesystem mount
specification of the form
\&'<type>:<fuse command> <mountpoint>'
\- where <type> is 'container' or
\&'host', specifying where the mount
will be performed
('container\-daemon' or 'host\-daemon'
will run the FUSE process detached).
<fuse command> is the path to the
FUSE executable, plus options for
the mount. <mountpoint> is the
location in the container to which
the FUSE mount will be attached.
E.g. 'container:sshfs 10.0.0.1:/
/sshfs'. Implies \fB\-\-pid\fR.
.TP
\fB\-h\fR, \fB\-\-help\fR
help for run
.TP
\fB\-H\fR, \fB\-\-home\fR string
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.
(default "/home/buildd")
.TP
\fB\-\-hostname\fR string
set container hostname. Infers \fB\-\-uts\fR.
.TP
\fB\-i\fR, \fB\-\-ipc\fR
run container in a new IPC namespace
.TP
\fB\-\-keep\-layers\fR
Keep layers when creating an
OCI\-SIF. Do not squash to a single layer.
.TP
\fB\-\-keep\-privs\fR
let root user keep privileges in
container (root only)
.TP
\fB\-\-memory\fR string
Memory limit in bytes
.TP
\fB\-\-memory\-reservation\fR string
Memory soft limit in bytes
.TP
\fB\-\-memory\-swap\fR string
Swap limit, use \fB\-1\fR for unlimited swap
.TP
\fB\-\-mount\fR stringArray
a mount specification e.g.
\&'type=bind,source=/opt,destination=/hostopt'.
.TP
\fB\-n\fR, \fB\-\-net\fR
run container in a new network
namespace (sets up a bridge network
interface by default)
.TP
\fB\-\-network\fR string
specify desired network type
separated by commas, each network
will bring up a dedicated interface
inside container (default "bridge")
.TP
\fB\-\-network\-args\fR strings
specify network arguments to pass to
CNI plugins
.TP
\fB\-\-no\-compat\fR
(\fB\-\-oci\fR mode) do not apply settings
for increased OCI/Docker
compatibility. Emulate native
runtime defaults without \fB\-\-contain\fR etc.
.TP
\fB\-\-no\-eval\fR
do not shell evaluate env vars or
OCI container CMD/ENTRYPOINT/ARGS
.TP
\fB\-\-no\-home\fR
do NOT mount users home directory if
\fI\,/home\/\fP is not the current working
directory
.TP
\fB\-\-no\-https\fR
use http instead of https for
docker:// oras:// and
library://<hostname>/... URIs
.TP
\fB\-\-no\-init\fR
do NOT start shim process with \fB\-\-pid\fR
.TP
\fB\-\-no\-mount\fR strings
disable one or more 'mount xxx'
options set in singularity.conf,
specify absolute destination path to
disable a bind path entry, or
\&'bind\-paths' to disable all bind
path entries.
.TP
\fB\-\-no\-oci\fR
Launch container with native runtime
.TP
\fB\-\-no\-pid\fR
do not run container in a new PID
namespace
.TP
\fB\-\-no\-privs\fR
drop all privileges in container
(root only in non\-OCI mode)
.TP
\fB\-\-no\-setgroups\fR
disable setgroups when entering
\fB\-\-fakeroot\fR user namespace
.TP
\fB\-\-no\-tmp\-sandbox\fR
Prohibits unpacking of images into
temporary sandbox dirs
.TP
\fB\-\-no\-umask\fR
do not propagate umask to the
container, set default 0022 umask
.TP
\fB\-\-nv\fR
enable Nvidia support
.TP
\fB\-\-nvccli\fR
use nvidia\-container\-cli for GPU
setup (experimental)
.TP
\fB\-\-oci\fR
Launch container with OCI runtime
(experimental)
.TP
\fB\-\-oom\-kill\-disable\fR
Disable OOM killer
.TP
\fB\-o\fR, \fB\-\-overlay\fR strings
use an overlayFS image for
persistent data storage or as
read\-only layer of container
.TP
\fB\-\-passphrase\fR
prompt for an encryption passphrase
.TP
\fB\-\-pem\-path\fR string
enter an path to a PEM formatted RSA
key for an encrypted container
.TP
\fB\-p\fR, \fB\-\-pid\fR
run container in a new PID namespace
.TP
\fB\-\-pids\-limit\fR int
Limit number of container PIDs, use
\fB\-1\fR for unlimited
.TP
\fB\-\-rocm\fR
enable experimental Rocm support
.TP
\fB\-S\fR, \fB\-\-scratch\fR strings
include a scratch directory within
the container that is linked to a
temporary dir (use \fB\-W\fR to force location)
.TP
\fB\-\-security\fR strings
enable security features (SELinux,
Apparmor, Seccomp)
.TP
\fB\-\-tmp\-sandbox\fR
Forces unpacking of images into
temporary sandbox dirs when a kernel
or FUSE mount would otherwise be used.
.TP
\fB\-u\fR, \fB\-\-userns\fR
run container in a new user
namespace, allowing Singularity to
run completely unprivileged on
recent kernels. This disables some
features of Singularity, for example
it only works with sandbox images.
.TP
\fB\-\-uts\fR
run container in a new UTS namespace
.TP
\fB\-W\fR, \fB\-\-workdir\fR string
working directory to be used for
\fI\,/tmp\/\fP and \fI\,/var/tmp\/\fP (if \fB\-c\fR/\-\-contain
was also used)
.TP
\fB\-w\fR, \fB\-\-writable\fR
by default all Singularity
containers are available as read
only. This option makes the file
system accessible as read/write.
.TP
\fB\-\-writable\-tmpfs\fR
makes the file system accessible as
read\-write with non persistent data
(with overlay support only)
.SH EXAMPLES
.IP
# Here we see that the runscript prints "Hello world: "
$ singularity exec /tmp/debian.sif cat /singularity
#!/bin/sh
echo "Hello world: "
.IP
# It runs with our inputs when we run the image
$ singularity run /tmp/debian.sif one two three
Hello world: one two three
.IP
# Note that this does the same thing
$ ./tmp/debian.sif one two three
.PP
For additional help or support, please visit https://www.sylabs.io/docs/