apptainer-shell

Start an interactive shell inside a container

$ apptainer shell [container.sif]

$ apptainer shell --bind [/host/path]:[/container/path] [container.sif]

$ apptainer shell docker://[ubuntu:latest]

$ apptainer shell --nv [container.sif]

$ apptainer shell --cleanenv [container.sif]

$ apptainer shell --containall [container.sif]

$ apptainer shell --overlay [overlay.img] [container.sif]

$ apptainer shell --fakeroot [container.sif]

apptainer shell [options] container

apptainer shell starts an interactive shell session inside an Apptainer container. This provides a command-line environment within the container for exploration, debugging, and interactive work.
By default, the shell inherits your user identity, home directory, and current working directory. The host environment is largely preserved unless containment options are used. This makes the shell feel familiar while providing access to the container's filesystem and installed software.
The container can be specified as a local SIF file, a Docker reference (docker://), a library reference (library://), or an OCI archive. The default shell is /bin/sh but can be overridden with the --shell option if the container has other shells available.
For development work, combine --overlay or --writable-tmpfs to allow temporary modifications within the container. Use --fakeroot when operations require apparent root privileges without actual host root access.

--bind, -B src[:dest[:opts]]

Bind mount a host path into the container.

Use overlay filesystem for writable layer.

Enable NVIDIA GPU support.

Enable AMD ROCm GPU support.

Use minimal /dev and empty other directories.

Full containment with clean environment and PID namespace.

Clean environment before starting shell.

Set environment variable in container.

Set custom home directory.

Initial working directory in container.

Run with fake root privileges.

Enable network namespace.

Specify shell to use (default: /bin/sh).

Add writable tmpfs overlay.

Do not bind the home directory.

Shell availability depends on what's installed in the container. Some minimal containers may only have /bin/sh. Environment leakage from host to container can cause unexpected behavior; use --cleanenv for reproducibility. Changes made during shell session are lost unless using writable overlays or bind mounts.

The shell command has been a core Singularity/Apptainer feature since the project's creation at Lawrence Berkeley National Laboratory in 2015. It was designed to give users familiar interactive access to containers, supporting the HPC use case where users need to test and debug within container environments. Apptainer maintained full compatibility with this command when forking from Singularity in 2021.

apptainer(1), apptainer-exec(1), apptainer-run(1), apptainer-build(1)