apptainer(1)

✨ NAME ✨

apptainer-instance-run — run a named instance of the given container image. Okay so welcome to apptainer(1), bestie: this page is all about giving your container a name and letting it do its thing in the background. It’s giving main character energy, but make it background-process chic. 💅

🦋 SYNOPSIS 🦋

apptainer instance run [start options...]   [runscript args...]

🎀 DESCRIPTION 🎀

The instance run command lets you create a new named instance from an existing container image, and that instance starts running in the background. If a runscript is defined in the container metadata, the commands in that script get executed with the instance run command too. You can optionally pass arguments to the runscript. No cap. ✨

NOTE: This command was added to Apptainer significantly later than the other action commands and will not work with older containers. In that case, you may need to rebuild the container. 💀

apptainer instance run accepts the following container formats:

• .sif — Singularity Image Format (SIF) — Native to Singularity 3.0+ and all Apptainer versions.
• .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 💅

• --add-caps="" — a comma-separated capability list to add. Like, sprinkle in extra powers.
• --allow-setuid[=false] — allow setuid binaries in the container (root only).
• --app="" — set an application to run inside a container.
• --apply-cgroups="" — apply cgroups from a file for container processes (root only).
• --authfile="" — Docker-style authentication file used for writing/reading OCI registry credentials.
• -B, --bind=[] — a user-bind path specification. The 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 disables it.
• --blkio-weight-device=[] — device-specific block IO relative weight.
• --boot[=false] — execute /sbin/init to boot the container (root only).
• -e, --cleanenv[=false] — clean environment before running the 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 the container.
• --cpus="" — number of CPUs available to the container.
• --cpuset-cpus="" — list of host CPUs available to the container.
• --cpuset-mems="" — list of host memory nodes available to the 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 the container process (experimental).
• --dns="" — list of DNS servers 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 an environment variable to the contained process.
• --env-file=[] — pass environment variables from a file to the contained process.
• -f, --fakeroot[=false] — run the container with the appearance of running as root.
• --fusemount=[] — a FUSE filesystem mount specification. The manpage’s placeholder fields got a little eaten, but the literal bits are: the form uses ':'; container or host says where the mount will be performed (container-daemon or host-daemon will run the FUSE process detached); the path to the FUSE executable, plus options for the mount; and 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 run.
• -H, --home="/builddir" — a home directory specification. The spec can either be a src path or a 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 the container hostname.
• --intel-hpu[=false] — enable Intel(R) Gaudi accelerator support while using a minimal /dev.
• -i, --ipc[=false] — run the container in a new IPC namespace.
• --keep-privs[=false] — let the root user keep privileges in the 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 the 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 the container.
• --network-args=[] — specify network arguments to pass to CNI plugins.
• --no-env=[] — list of environment variables to block from import into the container from the host environment.
• --no-eval[=false] — do not shell evaluate env vars or OCI container CMD/ENTRYPOINT/ARGS.
• --no-home[=false] — do NOT mount the 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 an 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 the root user in the 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 a read-only layer of the 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 the instance PID to the file with the given name.
• --pids-limit=0 — limit the number of container PIDs; use -1 for unlimited.
• --rocm[=false] — enable experimental Rocm support.
• --runscript-timeout="" — set the timeout duration for the runscript (default 1m).
• -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 the container in a new user namespace.
• --uts[=false] — run the 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 🌸

$ apptainer instance run /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)

👑 HISTORY 👑

22-Oct-2026 — auto generated by spf13/cobra.

---

Okay that’s the whole vibe. This page is apptainer(1), auto generated by spf13/cobra, and it’s dated Oct 2026. Byeee bestie, go run that instance 💖✨