Configuring Podman for Quarkus Dev Services and Testcontainers on Linux

Podman is a daemonless container engine for developing, managing and running containers on Linux systems. Starting with release 3, Podman allows the user to run a service that mimics the Docker API. This allows Testcontainers and Quarkus Dev Services to be used with Podman.

The instructions in this article will not work on MacOS or Microsoft Windows.


  • Linux system with Podman 3.x installed

  • podman-docker, which emulates the Docker CLI for Quarkus Dev Services

  • podman-remote is installed for the verification step (optional)



The following commands will set up Podman and environment variables to work with Quarkus Dev Services and Testcontainers:

# Install the required podman packages from dnf. If you're not using rpm based
# distro, replace with respective package manager
sudo dnf install podman podman-docker
# Enable the podman socket with Docker REST API
systemctl --user enable podman.socket --now
# Set the required envvars
export DOCKER_HOST=unix:///run/user/${UID}/podman/podman.sock

Let’s take a look at what this configuration does below, along with some basic troubleshooting information.

Setting up the Podman service

Podman is a daemonless container engine. Quarkus Dev Services and Testcontainers expect a running Docker daemon to listen on a Unix socket. Since version 3, Podman can be configured to create a service listening on a Unix socket, and this service can be used with Dev Services and Testcontainers.

Docker clients are trying to connect to the service specified in the url specified in the environment variable DOCKER_HOSTso this variable needs to be set to point to the Unix socket that the Podman service will listen on:

export DOCKER_HOST=unix:///run/user/${UID}/podman/podman.sock

This parameter will only apply to the current terminal session. To make this configuration permanent, add a line to your shell profile files (e.g. ~ /.profile).

Testcontainers and Quarkus Dev Services also expect the container service they are accessing to be non-interactive. If you have multiple registries configured in your Docker or Podman configuration, Podman responds with a prompt asking which registry to use to fetch containers if the containers to retrieve are specified by their short name.

You can disable this prompt by setting the config property short-name-mode = "disabled" Podman’s /etc/containers/registries.conf… This setting can affect the security of the system. Please see short names of container images in Podman before changing this parameter.

Finally, let’s start the Podman service listening on the socket previously specified in the environment variable DOCKER_HOST

Podman is distributed with local custom systemd modules in the apt and dnf package managers configured to run the Podman service without root access. This means that the Podman process will only run with the privileges of the user you are logged in with. Therefore containers and config are stored in your home directory and therefore the service listens unix:///run/user/${UID}/podman/podman.sock… On most Linux distributions, you can enable this service with the following command:

systemctl --user enable podman.socket --now

You can verify that the container service is indeed running and responding at the URI given in DOCKER_HOSTusing podman-remote:

podman-remote info

Spoofing Ryuk container support is unstable at this time. Ryuk is a container that Testcontainers uses to clean up any containers after they have finished using them in Java code. You can configure Testcontainers to not use Ryuk:


This setting will also only apply to the current terminal session. To make this configuration permanent, add a line to your shell profile files (e.g. ~ / .profile).

Podman is now ready to respond to the Java Docker client used by Testcontainers. Please note that Quarkus Dev Services requires that the command docker was available in PATH… Plastic bag podman-docker on Linux distributions provides Docker CLI emulation layer for Podman.

In future releases of Quarkus, the need for a team docker available in PATH, will be removed.

Migrating from Docker

If you previously used versions of Docker that did not support V2 cgroups in modern Linux distributions, you had to use a crutch by setting cgroups to V1. This applied to Docker versions 19 and older inclusive.

You can check if this crutch has been previously used on your system with the following command:

sudo grubby --info=ALL | grep "systemd.unified_cgroup_hierarchy=0"

If the output is present, it means that the kernel argument for cgroups was set to V1. You can remove this kernel argument with the following command, re-enabling V2 cgroups:

sudo grubby --update-kernel=ALL --remove-args="systemd.unified_cgroup_hierarchy=0"

This setting will take effect only after a reboot.

This is how Podman can be configured for Quarkus Dev Services and Testcontainers on Linux.

From the translator: if you are interested in Quarkus, I invite you to join the telegram channel dedicated to this framework –

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *