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.

Windows

The binding between the Podman machine and the system socket is not known. So, Podman Desktop displays only the server information on the Docker Compatibility page.

macOS

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.

Linux

The binding between the Podman machine and the system socket is not known. So, Podman Desktop displays only the server information on the Docker Compatibility page.

Enable Docker compatibility

Prerequisites

• A running Podman machine.

Windows

Procedure

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

  A Docker Compatibility section is added to the list of Settings.

Verification

Perform any of the following steps:

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

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

• Run the docker context list command to check that the Docker CLI context is set to the default value npipe:////./pipe/docker_engine.

macOS

Procedure

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

2. Click Enable.

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. A Docker Compatibility 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.

Linux

Procedure

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

  A Docker Compatibility section is added to the list of Settings.

Verification

Perform any of the following steps:

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

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

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

Disable Docker compatibility

Prerequisites

• A running Podman machine.

Windows

Procedure

• 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 Compatibility section is removed from the list of Settings.

Verification

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

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

macOS

Procedure

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

2. Click Disable.

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 Compatibility 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

Linux

Procedure

• 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 Compatibility section is removed from the list of Settings.

Verification

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

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

Additional resources

• Managing Docker compatibility
• podman-mac-helper source