From ArchWiki
Jump to navigation Jump to search

Podman is an alternative to Docker, providing a similar interface.


Install the podman package. Additionally if you want to build container images look at Buildah.

Unlike Docker, Podman does not require a daemon, but there is one providing an API for services like cockpit via cockpit-podman.

By default it is only possible to run Podman containers as root. See Rootless Podman to set up running containers as a non-root user.


Configuration files for configuring how containers behave are located at /etc/containers. To configure the network bridge interface used by Podman see /etc/cni/net.d/87-podman-bridge.conflist.

Rootless Podman

By default only root is allowed to run containers (or namespaces in kernelspeak).

Note: On linux-hardened kernel.unprivileged_userns_clone is set to 0 (but rootless podman requires it to be set to 1). Use sysctl or a kernel parameter to configure it.

Rootless Podman requires using cgroups v2. See cgroups on how to check whether v1 (default) or v2 is used and how to switch to cgroups v2.

To allow rootless operation of Podman containers, first determine which user(s) and group(s) you want to use for the containers, and then add their corresponding entries to /etc/subuid and /etc/subgid respectively.

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: usermod's --add-subuids and --add-subgids options will not work if the /etc/subuid and /etc/subgid files do not exist. (Discuss in Talk:Podman#)

The following example enables the podman user and group to run Podman containers (or other types of containers in that case). It allocates the UIDs and GIDs from 165536 to 169631 to the podman user and group respectively. This can be achieved either by editing these files directly or with usermod(8). See subuid(5) and subgid(5) for more information.

# usermod --add-subuids 165536-231072 --add-subgids 165536-231072 podman
Note: Many images require 65536 uids / gids for mapping (notably the base busybox and alpine images). It is recommended that you allocate at least that many uids / gids for each user to maximize compatibility with docker.

After this the user/group podman is able to start and run podman containers.


Note: You may omit the registry prefix from the images, as Podman will automatically search for the image in all registries defined in /etc/containers/registries.conf at registries.search in the defined order. The following images will always contain the prefix, to allow for configurations without docker.io in the configuration.

Arch Linux

The following command pulls the Arch Linux x86_64 image from Docker Hub. This is a stripped down version of Arch core without network, etc.

# podman pull docker.io/archlinux

See also README.md.

For a full Arch base, clone the repo from above and build your own image.

$ git clone https://github.com/archlinux/archlinux-docker.git

Make sure that the devtools package is installed.

Edit the packages file so it only contains 'base'. Then run:

# make rootfs
# podman build -t archlinux .

Alpine Linux

Alpine Linux is a popular choice for small container images, especially for software compiled as static binaries. The following command pulls the latest Alpine Linux image from Docker Hub:

# podman pull docker.io/alpine

Alpine Linux uses the musl libc implementation instead of the glibc libc implementation used by most Linux distributions. Because Arch Linux uses glibc, there are a number of functional differences between an Arch Linux host and an Alpine Linux container that can impact the performance and correctness of software. A list of these differences is documented in https://wiki.musl-libc.org/functional-differences-from-glibc.html.

Note that dynamically linked software built on Arch Linux (or any other system using glibc) may have bugs and performance problems when run on Alpine Linux (or any other system using a different libc). See [1], [2] and [3] for examples.


The following command pulls the latest CentOS image from Docker Hub:

# podman pull docker.io/centos

See the Docker Hub page for a full list of available tags for each CentOS release.


The following command pulls the latest Debian image from Docker Hub:

# podman pull docker.io/debian

See the Docker Hub page for a full list of available tags, including both standard and slim versions for each Debian release.

See also