Skip to main content

Aliasing the Docker CLI

If you remove Docker, the docker command goes with it. Your scripts, your shell history, and the many docker examples you find online all stop working, even though Podman can run most of them.

Because the Podman CLI is a drop-in replacement for most Docker commands, you can make docker run Podman instead. You then keep using the commands you already know, and your scripts continue to work without changes.

note

Aliasing the Docker CLI changes which program the docker command runs. It does not affect tools that connect to the Docker socket directly, such as Testcontainers or Maven. To make those tools work with Podman, enable Docker compatibility or set the DOCKER_HOST environment variable.

Prerequisites​

  • A running Podman machine.
  • No docker command on your system, or one that you want to replace. To check, run command -v docker on Linux and macOS, or Get-Command docker on Windows.

Choosing an approach​

A shell alias is the quickest way to get a docker command, but it exists only inside the shell that defines it, and no other program on your system can see it. If your goal is to keep existing scripts working, do not rely on a shell alias. The other approaches put a real docker command on your PATH, so everything on your system finds it.

ApproachWorks in scriptsSurvives a new terminalPlatform
Shell aliasNoOnly if you edit your shell profileLinux, macOS
PowerShell aliasOnly in the same sessionOnly if you edit your PowerShell profileWindows
podman-docker packageYesYesLinux
Symbolic linkYesYesLinux, macOS
Wrapper scriptYesYesLinux, macOS, Windows

Creating a shell alias​

Use an alias when you want a docker command in your own terminal and you do not need other programs to find it.

Procedure​

  1. Create the alias in your current PowerShell session:

    $ Set-Alias -Name docker -Value podman

  2. Optional: To make the alias available in every new PowerShell session, add the same command to your PowerShell profile. The profile path is stored in the $PROFILE variable.

    The profile file does not exist on a new PowerShell installation. Create the file, and the parent directory, if needed:

    $ if (!(Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force }

    Add the alias to the profile:

    $ Add-Content -Path $PROFILE -Value 'Set-Alias -Name docker -Value podman'

    Your execution policy must also allow the profile to run. The Restricted policy blocks all script files, including profiles, and is the effective policy on Windows clients when no policy is set in any scope.

    Check the effective policy:

    $ Get-ExecutionPolicy

    Check the policy for each scope:

    $ Get-ExecutionPolicy -List

    If your execution policy prevents the profile from running, create a persistent docker command instead.

    PowerShell scripts that you run from the same session can use the alias. Other programs and cmd.exe scripts cannot.

Verification​

  • Check that the docker command runs Podman:

    $ docker --help

    The output starts with the Podman description:

    Manage pods, containers and images

Creating a persistent Docker command​

Create a persistent docker command when you want your scripts, build tools, and other programs to find it.

Procedure​

  1. Create the C:\Program Files\docker\bin directory. If you removed Docker, this directory no longer exists.

    $ New-Item -ItemType Directory -Force -Path 'C:\Program Files\docker\bin'

    Writing to C:\Program Files and editing the system PATH both require administrator permissions, so run PowerShell as an administrator. Alternatively, use a directory in your user profile and add it to your user PATH.

  2. Create a C:\Program Files\docker\bin\docker.bat file with the following content:

    @echo off
    REM Delete the next line to stop showing this message.
    echo Emulate Docker CLI using podman. 1>&2
    podman %*

    The reminder goes to standard error, so that it does not appear in output that your scripts capture.

  3. Add C:\Program Files\docker\bin to the PATH environment variable.

  4. Close all cmd and PowerShell windows, then open a new one.

    Programs read the PATH variable when they start, so open windows do not pick up the change.

note

A batch file is not an executable. This affects how other programs run the docker command:

  • Programs that start docker without a shell cannot run docker.bat. Node.js execFile() is one example.
  • In a batch script, run call docker ... rather than docker .... Without call, control does not return to your script.

Verification​

  1. Check that the docker command runs Podman:

    $ docker --help

    The output starts with the reminder from the docker.bat file:

    Emulate Docker CLI using podman.

    The rest of the output includes the Podman description:

    Manage pods, containers and images

  2. Run a container:

    $ docker run docker.io/hello-world

Podman supports most Docker commands, but not all of them behave identically. If a command does not work as you expect, see the Podman documentation.

Additional resources​