Podman is an alternative to Docker, providing a similar interface. It supports rootless containers and a shim service for docker-compose.
If you want to replace Docker, one can install to mimic the docker binary along with man pages.
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
/usr/share/containers/. You must copy necessary files to
/etc/containers before edit. To configure the network bridge interface used by Podman see
CONFIG_USER_NS_UNPRIVILEGED) which has some serious security implications, see Security#Sandboxing applications for details.
By default only
root is allowed to run containers (or namespaces in kernelspeak). Running rootless Podman improves security as an attacker will not have root privileges over your system, and also allows multiple unprivileged users to run containers on the same machine. See also .
First, check the value of
kernel.unprivileged_userns_clone by running:
$ sysctl kernel.unprivileged_userns_clone
Set subuid and subgid
In order for users to run rootless Podman, a
/etc/subgid which lists the UIDs for their user namespace.
/etc/subgid do not exist by default. If they do not exist yet in your system, create them by running:
# touch /etc/subuid /etc/subgid
The following command enables the
username user and group to run Podman containers (or other types of containers in that case). It allocates a given range of UIDs and GIDs to the given user and group.
# usermod --add-subuids 100000-165535 --add-subgids 100000-165535 username
Now, you should have the following content (replacing
username with the given username):
Propagate changes to subuid and subgid
Rootless Podman uses a pause process to keep the unprivileged namespaces alive. This prevents any change to the
/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 specified in the above files is able to start and run Podman containers.
The configuration for how and where container images and instances are stored takes place in
$XDG_CONFIG_HOME/containers/storage.confon a per-user basis.
driver according to the filesystem in use for the storage location (see ).
Podman is able to run images built for different CPU architecture than host using Wikipedia:binfmt_misc system.
To enable it installAUR and AUR packages.
systemd comes with
systemd-binfmt.service service which should enable new rules.
Verify that binfmt rules have been added:
DOSWin qemu-cris qemu-ppc qemu-sh4eb status qemu-aarch64 qemu-m68k qemu-ppc64 qemu-sparc qemu-alpha qemu-microblaze qemu-riscv64 qemu-sparc32plus qemu-arm qemu-mips qemu-s390x qemu-sparc64 qemu-armeb qemu-mipsel qemu-sh4 register
Podman should now be able to run foreign architecture images. Most commands use the foreign architecture when
--arch option is passed.
podman run --arch arm64 'docker.io/alpine:latest' arch
Podman 3.0.0 introduces docker-compose support. This requires enabling a Podman socket which pretends to be docker; start the
podman.service unit. For rootless containers, this requires you to start the
podman.service user unit instead and set the
$ export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"
To get hostname resolution between containers running install.
unqualified-search-registriesin the defined order. The following images will always contain the prefix, to allow for configurations without
docker.ioin the configuration.
# podman pull docker.io/archlinux
See also README.md.
For a full Arch base, clone the repo from above and build your own image.
Make sure that thepackage is installed.
packages file so it only contains 'base'. Then run:
# make rootfs # podman build -t archlinux .
# 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 ,  and  for examples.
# podman pull docker.io/centos
See the Docker Hub page for a full list of available tags for each CentOS release.
# 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: https://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
owner /run/user/[0-9]*/containers/cni/dnsname/*/dnsmasq.conf r, owner /run/user/[0-9]*/containers/cni/dnsname/*/addnhosts r, owner /run/user/[0-9]*/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
Error on commit in rootless mode
Error committing the finished image: error adding layer with blob "sha256:02823fca9b5444c196f1f406aa235213254af9909fca270f462e32793e2260d8": Error processing tar file(exit status 1) permitted operation
Check that the storage driver is overlay in the #Storage configuration.