apptainer(1)

apptainer(1) 💖 — instance start, bestie!

okay so you opened the apptainer manual page and we’re zooming straight in on apptainer instance start, the “make my container run in the background with a name” command. It’s giving background-process main character energy, fr fr. Hydrate and let’s go. 🦋

NAME ✨

apptainer-instance-start — start a named instance of the given container image. literally the named-instance starter, periodt. 💅

SYNOPSIS 🚀

apptainer instance start [start options...]   [startscript args...]

DESCRIPTION 🌸

okay so the instance start command lets you create a new named instance from an existing container image, and that instance begins running in the background. If a startscript is defined in the container metadata, the commands in that script will be executed with the instance start command as well. You can optionally pass arguments to startscript. cute. 🎀

apptainer instance start accepts these container formats:

• .sif — Singularity Image Format (SIF) — native to Singularity 3.0+ and all Apptainer versions. iconic. 💖
• .sqsh — SquashFS format — native to Singularity 2.4+ and < 3.0.
• .img — ext3 format — native to Singularity versions < 2.4.
• directory/ — sandbox format — a 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 library enabled by 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.
• ipfs:// — a SIF image from an IPFS cluster, using a HTTP gateway.

OPTIONS 💅

not me about to list every single flag, but here we are: no skipping, no summarizing, every default stays. 😭✨

• --add-caps="" — a comma separated capability list to add.
• --allow-setuid[=false] — allow setuid binaries in container (root only). root-only, so respect the crown 👑.
• --app="" — set an application to run inside a container.
• --apply-cgroups="" — apply cgroups from file for container processes (root only).
• --authfile="" — Docker-style authentication file to use for writing/reading OCI registry credentials.
• -B, --bind=[] — 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.
• --blkio-weight=0 — Block IO relative weight in range 10-1000, 0 to disable.
• --blkio-weight-device=[] — Device specific block IO relative weight.
• --boot[=false] — execute /sbin/init to boot container (root only).
• -e, --cleanenv[=false] — clean environment before running container.
• --compat[=false] — apply settings for increased OCI/Docker compatibility. Infers --containall, --no-init, --no-umask, --no-eval, --writable-tmpfs.
• -c, --contain[=false] — use minimal /dev and empty other directories (e.g. /tmp and $HOME) instead of sharing filesystems from your host.
• -C, --containall[=false] — contain not only file systems, but also PID, IPC, and environment.
• --cpu-shares=-1 — CPU shares for container.
• --cpus="" — Number of CPUs available to container.
• --cpuset-cpus="" — List of host CPUs available to container.
• --cpuset-mems="" — List of host memory nodes available to container.
• --disable-cache[=false] — do not use or create cache.
• --dmtcp-launch="" — checkpoint for dmtcp to save container process state to (experimental).
• --dmtcp-restart="" — checkpoint for dmtcp to use to restart container process (experimental).
• --dns="" — list of DNS server separated by commas to add in resolv.conf.
• --docker-host="" — specify a custom Docker daemon host.
• --docker-login[=false] — login to a Docker Repository interactively.
• --drop-caps="" — a comma separated capability list to drop.
• --env=[] — pass environment variable to contained process.
• --env-file=[] — pass environment variables from file to contained process.
• -f, --fakeroot[=false] — run container with the appearance of running as root.
• --fusemount=[] — a FUSE filesystem mount specification of the form ':' — where [blank in the source text] is 'container' or 'host', specifying where the mount will be performed ('container-daemon' or 'host-daemon' will run the FUSE process detached). [blank in the source text] is the path to the FUSE executable, plus options for the mount. [blank in the source text] 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[=false] — help for start.
• -H, --home="/builddir" — 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.
• --hostname="" — set container hostname.
• --intel-hpu[=false] — enable Intel(R) Gaudi accelerator support while using a minimal /dev.
• -i, --ipc[=false] — run container in a new IPC namespace.
• --keep-privs[=false] — let root user keep privileges in container (root only).
• --memory="" — Memory limit in bytes.
• --memory-reservation="" — Memory soft limit in bytes.
• --memory-swap="" — Swap limit, use -1 for unlimited swap.
• --mount=[] — a mount specification e.g. 'type=bind,src=/opt,dst=/hostopt'.
• -n, --net[=false] — run container in a new network namespace (sets up a bridge network interface by default).
• --netns-path="" — join the network namespace at the specified path (as root, or if permitted in apptainer.conf).
• --network="" — specify desired network type separated by commas, each network will bring up a dedicated interface inside container.
• --network-args=[] — specify network arguments to pass to CNI plugins.
• --no-env=[] — list of environment variables to block from import into container from host environment.
• --no-eval[=false] — do not shell evaluate env vars or OCI container CMD/ENTRYPOINT/ARGS.
• --no-home[=false] — do NOT mount user’s home directory if /home is not the current working directory.
• --no-https[=false] — use http instead of https for docker://, oras:// and library:///... URIs.
• --no-init[=false] — do NOT start shim process with --pid.
• --no-mount=[] — disable one or more 'mount xxx' options set in apptainer.conf and/or specify absolute destination path to disable a bind path entry, or 'bind-paths' to disable all bind path entries.
• --no-privs[=false] — drop all privileges from root user in container.
• --no-umask[=false] — do not propagate umask to the container, set default 0022 umask.
• --nv[=false] — enable Nvidia support.
• --nvccli[=false] — use nvidia-container-cli for GPU setup (experimental).
• --oom-kill-disable[=false] — Disable OOM killer.
• -o, --overlay=[] — use an overlayFS image for persistent data storage or as read-only layer of container.
• --passphrase[=false] — prompt for an encryption passphrase.
• --pem-path="" — enter a path to a PEM formatted RSA key for an encrypted container.
• --pid-file="" — write instance PID to the file with the given name.
• --pids-limit=0 — Limit number of container PIDs, use -1 for unlimited.
• --rocm[=false] — enable experimental Rocm support.
• -S, --scratch=[] — include a scratch directory within the container that is linked to a temporary dir (use -W to force location).
• --security=[] — enable security features (SELinux, Apparmor, Seccomp).
• --unsquash[=false] — Convert SIF file to temporary sandbox before running.
• -u, --userns[=false] — run container in a new user namespace.
• --uts[=false] — run container in a new UTS namespace.
• -W, --workdir="" — working directory to be used for /tmp, /var/tmp and $HOME (if -c/--contain was also used).
• -w, --writable[=false] — by default all Apptainer containers are available as read only. This option makes the file system accessible as read/write.
• --writable-tmpfs[=false] — makes the file system accessible as read-write with non persistent data (with overlay support only).

EXAMPLE 🍓

here’s the vibe check in action, bestie:

$ apptainer instance start /tmp/my-sql.sif mysql

$ apptainer shell instance://mysql
Apptainer my-sql.sif> pwd
/home/mibauer/mysql
Apptainer my-sql.sif> ps
PID TTY          TIME CMD
  1 pts/0    00:00:00 appinit
  2 pts/0    00:00:00 bash
  3 pts/0    00:00:00 ps
Apptainer my-sql.sif>

$ apptainer instance stop /tmp/my-sql.sif mysql
Stopping /tmp/my-sql.sif mysql

SEE ALSO 🫶

• apptainer-instance(1) — go read the instance command group, iykyk.

HISTORY 🎀

the lore is literally:

22-Oct-2026 Auto generated by spf13/cobra

---

💖 final sign-off tea: this is the apptainer(1) page, and the footer says Auto generated by spf13/cobra with Oct 2026; the history date is 22-Oct-2026. byeee bestie, slay responsibly! 💋🌈