Using the podman-mac-helper
tool to migrate from Docker to Podman on macOS
Consider using podman-mac-helper
to migrate transparently to Podman on macOS.
- Continue using familiar Docker commands.
- Take advantage of the benefits of Podman on macOS.
- Your tools, such as Maven or Testcontainers, communicate with Podman without reconfiguration.
The podman-mac-helper
tool provides a compatibility layer that allows you to use most Docker commands with Podman on macOS.
The service redirects /var/run/docker
to the fixed user-assigned UNIX socket location.
Prerequisites
- macOS
- Podman
- Docker service is paused and Start Docker Desktop when you log in is disabled, or Docker is uninstalled.
Procedure
-
Set up the
podman-mac-helper
service: run the command in a terminal:sudo podman-mac-helper install
-
Restart your Podman machine: go to Settings > Resources, and in the Podman tile, click .
Verification
-
The Docker socket is a symbolic link for the Podman socket:
$ ls -la /var/run/docker.sock
The output points to a
podman.sock
file such as:/var/run/docker.sock -> /Users/username/.local/share/containers/podman/machine/podman.sock
-
When you query the Docker socket, you receive replies from Podman rather than Docker.
For instance, this command outputs Podman version rather that Docker version:
$ curl -s --unix-socket /var/run/docker.sock "http://v1.41/info" | jq -r .ServerVersion
-
Your tools communicating to the Docker socket, such as Maven or Testcontainers, communicate with Podman without reconfiguration.
-
(Optionally, if the
docker
CLI is installed) The docker CLI context is set to the default valueunix:///var/run/docker.sock
:$ docker context list
NAME TYPE DESCRIPTION DOCKER ENDPOINT KUBERNETES ENDPOINT ORCHESTRATOR
default * moby Current DOCKER_HOST based configuration unix:///var/run/docker.sock -
(Optionally, if the
docker
CLI is installed) Thedocker
CLI communicates with the Podman socket.Therefore this command outputs Podman version rather that Docker version:
$ docker info --format=json | jq -r .ServerVersion