Migrate from Docker to Podman on macOS

Docker announced the license and subscription plan changes for the Desktop Docker apps. Now at the latest, one can look for alternatives that have been around for a while. This article covers the replacement of Desktop Docker with podman on macOS.


Docker announced changes and introduction of special plans and subscription for the usage of Desktop Docker. This articles covers the activities to replace Desktop Docker on macOS with podman. Podman is a "a daemonless container engine for developing, managing, and running OCI Containers on your Linux System.". With the virtual machine support in Podman is it also possible to use it on macOS.

Replace toolset

Podman can be installed using brew:

brew install podman

podman machine init

Downloading VM image: fedora-coreos-34.20210821.1.1-qemu.x86_64.qcow2.xz: done
Extracting compressed file

podman machine start

INFO[0000] waiting for clients...
INFO[0000] listening tcp://
INFO[0000] new connection from  to /var/folders/6z/zxyfpch573122j4nzs9bqfvm0000gn/T/podman/qemu_podman-machine-default.sock
Waiting for VM ...
qemu-system-x86_64: warning: host doesn't support requested feature: CPUID.80000001H:ECX.svm [bit 2]

After the (re)start of the machine, which will use a Fedora VM is the environment available to execute and work with podman.

podman info

  arch: amd64
  buildahVersion: 1.22.3
  cgroupControllers: []
  cgroupManager: systemd
  cgroupVersion: v2
    package: conmon-2.0.29-2.fc34.x86_64
    path: /usr/bin/conmon
  APIVersion: 3.3.0
  Built: 1629488174
  BuiltTime: Fri Aug 20 19:36:14 2021
  GitCommit: ""
  GoVersion: go1.16.6
  OsArch: linux/amd64
  Version: 3.3.0

In the processes is the virtual machine - with qemu visible:

ps aux | grep qemu

xxx         78989   1.5  1.6  6621676 274412 s007  S     6:54PM   0:26.64 /usr/local/bin/qemu-system-x86_64 -m 2048 -smp 1 -fw_cfg name=opt/com.coreos/config,file=/Users/xxx/.config/containers/podman/machine/qemu/podman-machine-default.ign -qmp unix://var/folders/6z/zxyfpch573122j4nzs9bqfvm0000gn/T/podman/qmp_podman-machine-default.sock,server=on,wait=off -netdev socket,id=vlan,fd=3 -device virtio-net-pci,netdev=vlan,mac=5a:94:ef:e4:0c:ee -device virtio-serial -chardev socket,path=/var/folders/6z/zxyfpch573122j4nzs9bqfvm0000gn/T/podman/podman-machine-default_ready.sock,server=on,wait=off,id=podman-machine-default_ready -device virtserialport,chardev=podman-machine-default_ready,name=org.fedoraproject.port.0 -machine q35,accel=hvf:tcg -drive if=virtio,file=/Users/xxx/.local/share/containers/podman/machine/qemu/podman-machine-default_fedora-coreos-34.20210821.1.1-qemu.x86_64.qcow2 -display none


Most of the commands and parameters are still the same, replace "only" docker with podman, e.g. to

  • build
  • check the existing images
  • run a container
  • see which container/processes are running (ps)
podman build -f Dockerfile-custom -t tekton-101-podman:v1
STEP 1/7: FROM node:10
Resolving "node" using unqualified-search registries (/etc/containers/registries.conf)
Trying to pull registry.fedoraproject.org/node:10...
Trying to pull registry.access.redhat.com/node:10...
Trying to pull docker.io/library/node:10...
Getting image source signatures
Copying blob sha256:b800e94e7303e276b8fb4911a40bfe28f46180d997022c69bf1ee02fb7b86721
COMMIT tekton-101-podman:v1
--> 8edf0877768
Successfully tagged localhost/tekton-101-podman:v1

podman images
REPOSITORY                   TAG         IMAGE ID      CREATED        SIZE
localhost/tekton-101-podman  v1          8edf0877768e  2 minutes ago  959 MB
docker.io/library/node       10          28dca6642db8  4 months ago   940 MB

podman run --rm -p 49160:5000 -d -e TEKTON_101_ENV_NAME=App1 -e TEKTON_101_ENV_EXAMPLE=Version-0.1 -e TEKTON_101_ENV_DELAY=1 --name tekton-test tekton-101-podman:v1

podman ps
CONTAINER ID  IMAGE                           COMMAND      CREATED             STATUS                 PORTS                    NAMES
d30d314dc534  localhost/tekton-101-podman:v1  node app.js  12 seconds ago      Up 11 seconds ago>5000/tcp  tekton-test

curl localhost:49160
[App1]: Hello from NodeJS Playground! TEKTON_101_ENV_EXAMPLE=Version-0.1

Environment variables:

Request Headers:

Also the command to enter a container or to retrieve the logs are the same:

podman exec -ti tekton-test /bin/sh
# ls
Dockerfile-custom  README.adoc	dc.yaml       helm-ocp	k8s-compact   ocp-compact  openshift-2	      package.json  route.yaml	svc.yaml
LICENSE		   app.js	devfile.yaml  k8s	node_modules  openshift    package-lock.json  pipelines     static

podman logs -f tekton-test
App.Version: undefined
ENV.TEKTON_101: App1
Node app is running at http://localhost:5000
user-agent: curl/7.52.1

Other helpful commands

  • podman rm -f tekton-test2 delete (running) container
  • podman tag tekton-101-podman:v1 tekton-101-podman:v1.alpha re-tag existing image and tag

Remove Desktop Docker

Select in the Desktop Docker menu

  • Troubleshoot
  • Press Clean / Purge data
  • wait for completion
  • Again in Troubleshoot press Reset to factory details
  • Again in Troubleshoot press Uninstall
  • in Finder > Applications: search for Docker and Move to Bin
  • Remove the user-specific docker directory rm -rf ~/.docker


Invalid format in config.json

podman build -f Dockerfile-custom -t tekton-101-podman:v1
Error: failed to parse query parameter 'X-Registry-Config': "n/a": error storing credentials in temporary auth file (server: "https://index.docker.io/v1/", user: ""): key https://index.docker.io/v1/ contains http[s]:// prefix

Fix/remove the json object in .docker/config.json for the given key (here: https://index.docker.io/v1/).


Error: error creating build container: short-name resolution enforced but cannot prompt without a TTY

Docker prefixed the image names in Dockerfiles with docker.io or docker.io/library/ if they relative/short-names. From security purposes is this in podman not the preferred way.

If this advisable and secured configuration is not wanted and smooth migration, with similar weak security settings as with Docker, use the following approach to fix

Change the short-name-mode to permissive in the machine instance of podman (by default: Fedora), set also the registries which will be searched to find the image (parameter unqualified-search-registries) For more detailed information see the following article

podman machine ssh

less /etc/containers/registries.conf | grep 'unqualified-search-registries\|short-name-mode'
unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "quay.io"]

sudo vi /etc/containers/registries.conf

less /etc/containers/registries.conf | grep 'unqualified-search-registries\|short-name-mode'
unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "docker.io", "quay.io"]

Alternatively - and more secured way - use full qualified names in FROM of a Dockerfile.

FROM docker.io/library/node:10

# ...

Port-forwarding not working

podman run --rm -p 49160:5000 ... --name tekton-test tekton-101-podman:v1

podman ps
CONTAINER ID  IMAGE                           COMMAND      CREATED        STATUS            PORTS                    NAMES
d30d314dc534  localhost/tekton-101-podman:v1  node app.js  8 minutes ago  Up 8 minutes ago>5000/tcp  tekton-test

curl localhost:49160
curl: (7) Failed to connect to localhost port 49160: Connection refused

Is currently a bug in podman 3.3.1 and will be probably fixed i 3.3.2. Workaround is e.g to enhance locally ~/.config/containers/containers.conf and set rootless_networking = "cni"

less ~/.config/containers/containers.conf
  log_size_max = -1
  pids_limit = 2048
  userns_size = 65536
  rootless_networking = "cni"

But this still not work

podman run --rm -p 49160:5000 -d -e TEKTON_101_ENV_NAME=App1 -e TEKTON_101_ENV_EXAMPLE=Version-0.1 -e TEKTON_101_ENV_DELAY=1 --name tekton-test2 tekton-101-podman:v1
Error: error configuring network namespace for container a107005917b216de76ec20a8e64ca39041ba6140c224a8bb51150eea2729eefc: error adding pod tekton-test2_tekton-test2 to CNI network "podman": something went wrong with the request

It seems that the cni plugin with ports assignment does not work.

Alternative workaround is to use -P to publish all ports without specifying dedicated ports

podman run --rm -P -d -e TEKTON_101_ENV_NAME=App1 -e TEKTON_101_ENV_EXAMPLE=Version-0.1 -e TEKTON_101_ENV_DELAY=1 --name tekton-test2 tekton-101-podman:v1

podman ps
CONTAINER ID  IMAGE                           COMMAND      CREATED         STATUS             PORTS                    NAMES
ca865e1cdd2d  localhost/tekton-101-podman:v1  node app.js  15 seconds ago  Up 15 seconds ago>5000/tcp  tekton-test2

curl localhost:43031
[App1]: Hello from NodeJS Playground! TEKTON_101_ENV_EXAMPLE=Version-0.1

Environment variables:

Request Headers:


The replacement of Docker and Desktop Docker on a macOS through podman is very straightforward with few minor modifications. The transition is also simplified as most of the commands and parameters are still supported and applicable in the same way.






Quarkus and IBM Cloud Code Engine


Migrate from Wordpress to Gatsby and Netlify