Apptainer: a different distrobox alternative to manage containers

Apptainer is a container platform which integrates with the host (like distrobox) but with some key features, like easy to transport and share single-file containers.

Table of Contents


Apptainer containers are single files which are created on your working directory (by default) and therefore, they are easy to share. The host system shares some directories with the container ($HOME, /tmp and $PWD) but you can mount additional directories.


Apptainer is available on Arch Linux (‘community’ repository), Fedora, RHEL (with EPEL repositories) and as a DEB package for Debian/Ubuntu. Check for more info.


Pull images and create containers

Pull an image and create the container:

apptainer pull <URI>
  • <URI> can be a Docker/OCI image from Docker Hub or another OCI registry: docker://user/image:tag. For example docker://debian.

The container will be created as a .sif file inside your current directory.

Run a container

  • You can start a simple shell on your container with apptainer shell <container file>:
    apptainer shell debian-latest.sif
  • Run a single command with apptainer exec <container file> <command>:
    apptainer exec alpine-latest.sif cat /etc/os-release

Apptainer Definition Files

You can easily define your custom containers using a definition file. The content of a definition file can be as simple as:

Bootstrap: docker
From: debian:latest

  apt update
  apt -y upgrade
  apt install -y htop

  • Bootstrap: it determines the bootstrap agent that will be used to create the base operating system you want to use.
  • From defines the container to use as a base.
  • %post is executed at build time, after the base OS is installed.
  • %runscript defines actions to execute when the container is executed (apptainer run <container file>).
  • There are other sections inside a definition file, check

Apptainer Definition Files usually have the .def extension (but they are simple plain text files).

Build a container from scratch

After creating the Apptainer Definition File, you can create your custom container with apptainer build <container file> <definition file>:

apptainer build mydebian.sif deb-definition.def

More commands

  • apptainer run <container file>: run the user-defined default command within a container (%runscript section on the definition file).
  • apptainer inspect <container file>: shows metadata for a container.
  • apptainer help <command>: help about any Apptainer command. Run apptainer help for global help.