Skip to main content

Customizing Docker compatibility - Experimental feature

With Podman Desktop, you can customize the Docker compatibility feature. If you want to run your Docker applications on a Podman engine, you can enable the feature.

Podman Desktop uses the podman-mac-helper utility to automatically link the Docker socket to the Podman machine. This utility provides a compatibility layer that allows you to:

  • Run Docker commands on a Podman engine.
  • Make your tools, such as Maven or Testcontainers communicate with Podman without reconfiguration.

Podman Desktop provides information about the Podman machine that emulates the Docker socket on the Docker Compatibility page. Click the Podman details icon to view the details of the Podman machine.

system socket details on macOS

Enable Docker compatibility​

Prerequisites​

Procedure​

  1. Click Docker Compatibility in the status bar. A notification opens.

  2. Click Enable. enable docker compatibility

  3. Enter your machine password when prompted. A successful operation notification opens.

  4. Click OK. A notification prompts you to restart your Podman machine.

  5. Click Yes. restart Podman machine

  6. Perform one of the following steps:

    • Go to Settings > Experimental, and click the toggle button. enable toggle button - Experimental
    • Go to Settings > Preferences > Experimental (Docker Compatibility), and click the toggle button. enable toggle button - Preferences A Docker Compatibilty section is added to the list of Settings.

Verification​

Perform any of the following steps:

  • Check whether 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, as shown below:

    /var/run/docker.sock -> /Users/username/.local/share/containers/podman/machine/podman.sock

  • Run the following command to check the output returns the Podman version rather than the Docker version:

    $ curl -s --unix-socket /var/run/docker.sock "http://v1.41/info"  | jq -r .ServerVersion

  • Run the docker context list command to check that the Docker CLI context is set to unix:///var/run/docker.sock.

Disable Docker compatibility​

Prerequisites​

Procedure​

  1. Click Docker Compatibility in the status bar. A notification opens.

  2. Click Disable. disable Docker compatibility

  3. Enter your machine password when prompted. A successful operation notification opens.

  4. Click OK. A notification prompts you to restart your Podman machine.

  5. Click Yes.

  6. Perform one of the following steps:

    • Go to Settings > Experimental, and click the toggle button.
    • Go to Settings > Preferences > Experimental (Docker Compatibility), and click the toggle button.

    The Docker Compatibilty section is removed from the list of Settings.

Verification​

Perform any of the following steps:

  • Check that the Docker socket is not a symbolic link for the Podman socket:

    $ ls -la /var/run/docker.sock

    The output returns the following:

    ls: /var/run/docker.sock: No such file or directory

  • Run the following command to check the output returns the Docker version rather than the Podman version:

    $ curl -s --unix-socket /var/run/docker.sock "http://v1.41/info"  | jq -r .ServerVersion

Additional resources​