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.

Rootless Podman uses a pause process to keep the unprivileged namespaces alive. This prevents any change to the /etc/subuid and /etc/subgid files from being propagated to the rootless containers while the pause process is running. For these changes to be propagated it is necessary to run:

$ podman system migrate

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.


Containers terminate on shell logout

It may happen that after logging out from machine, Podman containers are stopped. To prevent that, user lingering should be enabled for user running containers:

$ loginctl enable-linger

You can also create user systemd unit as described: http://docs.podman.io/en/latest/markdown/podman-auto-update.1.html#examples

Error when creating a container with bridge network in rootless mode

If you are using AppArmor you might end up with problems when creating container using a bridge network with the dnsname plugin enabled:

$ podman network create foo
$ podman run --rm -it --network=foo docker.io/library/alpine:latest ip addr
Error: command rootless-cni-infra [alloc 89398a9315256cb1938075c377275d29c2b6ebdd75a96b5c26051a89541eb928 foo festive_hofstadter    ] in container 1f4344bbd1087c892a18bacc35f4fdafbb61106c146952426488bc940a751efe failed with status 1, stdout="", stderr="exit status 3\n"

This can be solved by adding the following lines to /etc/apparmor.d/local/usr.sbin.dnsmasq:

@{run}/containers/cni/dnsname/*/dnsmasq.conf r,
@{run}/containers/cni/dnsname/*/addnhosts r,
@{run}/containers/cni/dnsname/*/pidfile rw,

And then reloading the AppArmor profile:

# apparmor_parser -R /etc/apparmor.d/usr.sbin.dnsmasq
# apparmor_parser /etc/apparmor.d/usr.sbin.dnsmasq

See also