From ArchWiki
Jump to navigation Jump to search

Buildah is a tool that facilitates building Open Container Initiative (OCI) container images. The Buildah package provides a command line tool that can be used to:

  • create a working container, either from scratch or using an image as a starting point
  • create an image, either from a working container or via the instructions in a Dockerfile
  • images can be built in either the OCI image format or the traditional upstream docker image format
  • mount a working container's root filesystem for manipulation
  • unmount a working container's root filesystem
  • use the updated contents of a container's root filesystem as a filesystem layer to create a new image
  • delete a working container or an image
  • rename a local container

The most widely known alternative for building containers is docker. Do note that Buildah does not run containers, for that you may want to consider podman.


Install the buildah package or, for the development version, the buildah-gitAUR package.

If you want to run as non-root user, also install fuse-overlayfsAUR for better performance and storage space efficiency.


Enable support to build unprivileged containers

Users wishing to use Buildah to build unprivileged containers need to complete additional setup steps.

Firstly, a kernel is required that has support for User Namespaces (a kernel with CONFIG_USER_NS). All Arch Linux kernels have support for CONFIG_USER_NS. However, due to more general security concerns, the default Arch kernel does ship with User Namespaces enabled only for the root user.

Enable the sysctl setting kernel.unprivileged_userns_clone to allow normal users to run unprivileged containers. This can be done for the current session with sysctl kernel.unprivileged_userns_clone=1 and can be made permanent with sysctl.d(5).

Finally, create both /etc/subuid and /etc/subgid to contain the mapping to the containerized uid/gid pairs for each user who shall be able to run the containers.[1] The example below is for the root user (and systemd system unit) and an example user buildah:


See also