Skip to main content

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​

Procedure​

  1. Set up the podman-mac-helper service: run the command in a terminal:

    sudo podman-mac-helper install

  2. Restart your Podman machine: go to Settings > Resources, and in the Podman tile, click .

Verification​

  1. 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

  2. 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

  3. Your tools communicating to the Docker socket, such as Maven or Testcontainers, communicate with Podman without reconfiguration.

  4. (Optionally, if the docker CLI is installed) The docker CLI context is set to the default value unix:///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

  5. (Optionally, if the docker CLI is installed) The docker CLI communicates with the Podman socket.

    Therefore this command outputs Podman version rather that Docker version:

    $ docker info --format=json | jq -r .ServerVersion

Additional resources​