Replacing Docker Desktop with Podman Desktop on macOS

» Post Updates

• 2023-02-17: There is an official documentation about migrating from Docker to Podman Desktop which I missed when searching for it. So instead of reading this post, you should checkout Migration from Docker to Podman Desktop first.

» Setup

Install Podman Desktop, e.g. with homebrew:

1

brew install podman-desktop

Install the Podman Helper for compatibility with tools using the Docker socket.

1

sudo podman-mac-helper install

» Adjust the Podman Machine

The Podman Machine is the QEMU based virtualized machine which runs the underlaying Linux installation, necessary for the container runtime.

At the date of writing, the resources of the machine could not be adjusted using the GUI, only on the command line.

To do so, you might have to stop the machine first:

1

podman machine stop

and start it again after doing the changes:

1

podman machine start

When you want to create a smaller disk, you have to remove the old machine and create a new one:

1
2

podman machine rm
podman machine init --disk-size 30 --cpus 2 --memory 2048

Increasing the disk, adjusting the CPUs count, and memory can be modified without recreation:

1

podman machine set --disk-size 50 --cpus 4 --memory 4096

When you need to run priviledged containers which should be able to modify your (virtualized) host machine, you have to enable this explicitly:

1

podman machine set --rootful

» Redirecting the docker command to podman

First I tried to use an alias which will point docker to podman but as it turned out, aliases are not recognized in Makefiles. Instead, I’ve created a Bash script with the name docker in a folder which is part of my $PATH variable:

1
2
3
4
5
6

#!/usr/bin/env bash
set -euo pipefail
RED='\\033[0;31m'
NO_COLOR='\\033[0m'
echo -e "${RED}WARNING: using podman${NO_COLOR}" 
podman "$@"

Lets assume I run the following command:

docker run -it --rm alpine

First, the script remembers me with a red hint that I’m running the command using podman and not docker, then it will simply execute podman followed by all the given arguments.

» Image Building

When building images with Docker which don’t have a registry in their tag, Docker will implicitly add a docker.io/ prefix to the tag. On the other hand, Podman will add a localhost/ prefix for those tags missing a registry and podman doesn’t want to be compatible with Docker here (Issue #1034). Thus, you have to add a docker.io/ prefix to the tag explicitly if you need this compatibility.

» Kind

For running Kind with Podman, you have to set the KIND_EXPERIMENTAL_PROVIDER=podman environment variable.

Loading images to your cluster won’t work the same way anymore:

1

kind load docker-image IMAGE_NAME

Needs to be replaced with:

1

kind load image-archive <(podman save IMAGE_NAME)

This might not be necessary anymore once unified image loading is implemented.