Skip to main content

Using the DOCKER_HOST environment variable

Consider using the DOCKER_HOST environment variable to migrate transparently from Docker to Podman Desktop on all platforms.

  • Continue using familiar Docker commands.
  • Take advantage of the benefits of Podman.
  • Your tools, such as Gradle or Testcontainers, communicate with Podman without reconfiguration.

Using the DOCKER_HOST environment variable, you can connect your Docker CLI to the Podman socket.

note

Alternatively, you can add a podman context by using the docker context create command.

  • For example, set the value of the context in this pattern on a macOS machine:

    docker context create podman --docker "host=unix://${HOME}/.local/share/containers/podman/machine/podman.sock"

    Where, the path specified after the unix:// scheme denotes the DOCKER_HOST value.

Then, you can run the docker context use podman command to switch to that context. This way you can use your Docker CLI to run your tasks on a remote Podman engine. When you run the docker ps command, it queries the Podman socket specified in the current context.

Prerequisites​

  • Podman

Procedure​

  1. Identify the location of your Podman pipe 
$ podman machine inspect --format '{{.ConnectionInfo.PodmanPipe.Path}}'

  1. Set the DOCKER_HOST environment variable to your Podman pipe location. You'll need to replace back slashes with forward slashes and add the npipe:// scheme to the path retrieved previously:

    Example:

    prefixpodman-pipe

    npipe:////./pipe/podman-machine-default

    Depending on your terminal emulator of preference, there is a little variation between the commands to set a session level environment variable:

    cmd - Command Prompt​
    set DOCKER_HOST=npipe://<inspect_command_output>
    Git Bash​
    export DOCKER_HOST=npipe://<inspect_command_output>
    Powershell​

    Don't miss the quotes used with the value. Otherwise, powershell will interpret it as a separate command instead of a value.

    $env:DOCKER_HOST="npipe://<inspect_command_output>"

    Ideally, you should set DOCKER_HOST at the system or user level environment variables (or even load it in your CL emulator init script of choice).

note

Setting the DOCKER_HOST environment variable isn't necessary on Windows because Podman also listens to the default docker_engine pipe. But, it might be necessary if you get the following error: Error: socket of machine is not set, while trying to use the podman compose command.

Verification​

  • Your tools using the DOCKER_HOST environment variable, such as Gradle or Testcontainers, communicate with Podman without reconfiguration.