Docker CLI and API version (in)compatibility with Podman Engine
Ok, this should be a quick one, but it got me at least twice so far, so it’s time to note it down.
Recently I updated both Podman Desktop (1.24.2) as well as Podman machine (after being 16+ months old).
However, there was no updates to the Podman engine (currently at 5.7.1).
I am using Docker CLI on macOS for all interaction with local images and containers, as Podman ensures API forwarding listening on /var/run/docker.sock.
Docker API clients (such is Docker CLI) default to this address. In most instances, you don’t need to set DOCKER_HOST.
Needless to say, just yesterday I also updated Docker CLI (29.1.5).
Until all of these updates, any Docker CLI command (such as docker images or docker image ls) was working without issues.
However, after the updates, I started getting this error:
1 | ❯ docker images |
I was able to find a hint about solution, although in different context, thanks to this SO question. Solution suggests that by placing {"min-api-version": "1.44"} inside ~/.config/docker/daemon.json or ~/.docker/daemon.json should make this issue go away. However, I had doubts that in my scenario that would help, because I am not using Docker engine (no Docker Desktop) and I don’t think that daemon.json configs are acknowledged by Podman.
Before going further into solutions, I really wanted to understand what is going on.
Quick look at output of docker version and things started to make sense.
1 | ❯ docker version |
So what are we dealing with here?
Docker CLI
v29.1.5(released on Jan 16, 2026) is configured with current maximum Docker Engine API version, which is1.52When this was released, they bumped the minimal supported Docker Engine API version to
1.44(see this for additional evidence).Podman Engine
v5.7.1(released on Dec 8th, 2025) is still configured for compatibility with Docker Engine API version1.41, but it will work with min Docker Engine API version1.24. I was also able to confirm this in Podman’s podman/version/version.go. Alternative way to confirm this is with the command below:1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46❯ curl --silent -XGET --unix-socket /var/run/docker.sock http://localhost/version | jq .
{
"Platform": {
"Name": "linux/arm64/fedora-43"
},
"Components": [
{
"Name": "Podman Engine",
"Version": "5.7.1",
"Details": {
"APIVersion": "5.7.1",
"Arch": "arm64",
"BuildTime": "2025-12-08T16:00:00-08:00", <---- Build time
"Experimental": "false",
"GitCommit": "f845d14e941889ba4c071f35233d09b29d363c75",
"GoVersion": "go1.25.4 X:nodwarf5",
"KernelVersion": "6.17.7-300.fc43.aarch64",
"MinAPIVersion": "4.0.0",
"Os": "linux"
}
},
{
"Name": "Conmon",
"Version": "conmon version 2.1.13, commit: ",
"Details": {
"Package": "conmon-2.1.13-2.fc43.aarch64"
}
},
{
"Name": "OCI Runtime (crun)",
"Version": "crun version 1.24\ncommit: 54693209039e5e04cbe3c8b1cd5fe2301219f0a1\nrundir: /run/user/501/crun\nspec: 1.0.0\n+SYSTEMD +SELINUX +APPARMOR +CAP +SECCOMP +EBPF +CRIU +LIBKRUN +WASM:wasmedge +YAJL",
"Details": {
"Package": "crun-1.24-1.fc43.aarch64"
}
}
],
"Version": "5.7.1",
"ApiVersion": "1.41", <----- THIS LINE
"MinAPIVersion": "1.24", <----- AND THIS LINE
"GitCommit": "f845d14e941889ba4c071f35233d09b29d363c75",
"GoVersion": "go1.25.4 X:nodwarf5",
"Os": "linux",
"Arch": "arm64",
"KernelVersion": "6.17.7-300.fc43.aarch64",
"BuildTime": "2025-12-08T16:00:00-08:00"
}
Basically, this new version of Docker CLI is capable of working with API versions [1.52, 1.44]. Podman Engine is expecting [1.41, 1.24].
And you can see that Podman team is already working on fixing this, in commit c9e2028.
For the solution, I simply configured my ~/.zshrc to set DOCKER_API_VERSION to 1.44.
1 | ❯ cat ~/.zshrc | grep DOCKER |
The DOCKER_API_VERSION environment variable is used to force the Docker client to use a specific version of the API when communicating with the Docker daemon (in my case Podman Engine). By default, the Docker client and SDKs use API version negotiation to automatically select a version supported by both the client and the Docker Engine. However, setting DOCKER_API_VERSION disables this negotiation and locks the client to the specified version.
Aside from possibility to be used for feature controls, the primary use of this env var is to resolve “client and server don’t have the same version” errors, which can occur if the client is newer than the daemon. If the client is newer than the daemon, the client can request API endpoints that the daemon doesn’t know about.
After this, everything started working again.
1 | ❯ docker images |
