Warning

You're browsing the documentation for an old version of Apptainer. Consider upgrading to the latest version of Apptainer.

Documentation for the latest version can always be found at:
https://apptainer.org/docs/user/latest/

apptainer shell

Run a shell within a container

Synopsis

apptainer shell supports the following formats:

*.sif Singularity Image Format (SIF). Native to Singularity (3.0+) and Apptainer (v1.0.0+)

*.sqsh SquashFS format. Native to Singularity 2.4+

*.img ext3 format. Native to Singularity versions < 2.4.

directory/ sandbox format. Directory containing a valid root file
system and optionally Apptainer meta-data.

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

library://* A SIF container hosted on a Library (no default)

docker://* A Docker/OCI container hosted on Docker Hub or another
OCI registry.

shub://* A container hosted on Singularity Hub.

oras://* A SIF container hosted on an OCI registry that supports
the OCI Registry As Storage (ORAS) specification.

apptainer shell [shell options...] <container>

Examples

$ apptainer shell /tmp/Debian.sif
Apptainer/Debian.sif> pwd
/home/gmk/test
Apptainer/Debian.sif> exit

$ apptainer shell -C /tmp/Debian.sif
Apptainer/Debian.sif> pwd
/home/gmk
Apptainer/Debian.sif> ls -l
total 0
Apptainer/Debian.sif> exit

$ sudo apptainer shell -w /tmp/Debian.sif
$ sudo apptainer shell --writable /tmp/Debian.sif

$ apptainer shell instance://my_instance

$ apptainer shell instance://my_instance
Apptainer: Invoking an interactive shell within container...
Apptainer container:~> ps -ef
UID        PID  PPID  C STIME TTY          TIME CMD
ubuntu       1     0  0 20:00 ?        00:00:00 /usr/local/bin/apptainer/bin/sinit
ubuntu       2     0  0 20:01 pts/8    00:00:00 /bin/bash --norc
ubuntu       3     2  0 20:02 pts/8    00:00:00 ps -ef

Options

    --add-caps string        a comma separated capability list to add
    --allow-setuid           allow setuid binaries in container (root only)
    --app string             set an application to run inside a container
    --apply-cgroups string   apply cgroups from file for container processes (root only)
-B, --bind stringArray       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.
-e, --cleanenv               clean environment before running container
    --compat                 apply settings for increased OCI/Docker compatibility. Infers --containall, --no-init, --no-umask, --writable-tmpfs.
-c, --contain                use minimal /dev and empty other directories (e.g. /tmp and $HOME) instead of sharing filesystems from your host
-C, --containall             contain not only file systems, but also PID, IPC, and environment
    --disable-cache          do not use or create cache
    --dns string             list of DNS server separated by commas to add in resolv.conf
    --docker-login           login to a Docker Repository interactively
    --drop-caps string       a comma separated capability list to drop
    --env strings            pass environment variable to contained process
    --env-file string        pass environment variables from file to contained process
-f, --fakeroot               run container in new user namespace as uid 0
    --fusemount 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 --pid.
-h, --help                   help for shell
-H, --home 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/runner")
    --hostname string        set container hostname
-i, --ipc                    run container in a new IPC namespace
    --keep-privs             let root user keep privileges in container (root only)
    --mount stringArray      a mount specification e.g. 'type=bind,source=/opt,destination=/hostopt'.
-n, --net                    run container in a new network namespace (sets up a bridge network interface by default)
    --network string         specify desired network type separated by commas, each network will bring up a dedicated interface inside container (default "bridge")
    --network-args strings   specify network arguments to pass to CNI plugins
    --no-home                do NOT mount users home directory if /home is not the current working directory
    --no-https               use http instead of https for docker:// oras:// and library://<hostname>/... URIs
    --no-init                do NOT start shim process with --pid
    --no-mount strings       disable one or more mount xxx options set in apptainer.conf
    --no-privs               drop all privileges from root user in container)
    --no-umask               do not propagate umask to the container, set default 0022 umask
    --nv                     enable Nvidia support
    --nvccli                 use nvidia-container-cli for GPU setup (experimental)
-o, --overlay strings        use an overlayFS image for persistent data storage or as read-only layer of container
    --passphrase             prompt for an encryption passphrase
    --pem-path string        enter an path to a PEM formatted RSA key for an encrypted container
-p, --pid                    run container in a new PID namespace
    --pwd string             initial working directory for payload process inside the container
    --rocm                   enable experimental Rocm support
-S, --scratch strings        include a scratch directory within the container that is linked to a temporary dir (use -W to force location)
    --security strings       enable security features (SELinux, Apparmor, Seccomp)
-s, --shell string           path to program to use for interactive shell
    --syos                   execute SyOS shell
-u, --userns                 run container in a new user namespace, allowing Apptainer to run completely unprivileged on recent kernels. This disables some features of Apptainer, for example it only works with sandbox images.
    --uts                    run container in a new UTS namespace
    --vm                     enable VM support
    --vm-cpu string          number of CPU cores to allocate to Virtual Machine (implies --vm) (default "1")
    --vm-err                 enable attaching stderr from VM
    --vm-ip string           IP Address to assign for container usage. Defaults to DHCP within bridge network. (default "dhcp")
    --vm-ram string          amount of RAM in MiB to allocate to Virtual Machine (implies --vm) (default "1024")
-W, --workdir string         working directory to be used for /tmp, /var/tmp and $HOME (if -c/--contain was also used)
-w, --writable               by default all Apptainer containers are available as read only. This option makes the file system accessible as read/write.
    --writable-tmpfs         makes the file system accessible as read-write with non persistent data (with overlay support only)

SEE ALSO

apptainer -

Linux container platform optimized for High Performance Computing (HPC) and Enterprise Performance Computing (EPC)

Auto generated by spf13/cobra on 16-Feb-2023