Troubleshooting Podman
Podman Desktop does not find your Podman installation
Issue
To install Podman, you can choose between multiple installation methods:
- Install from Podman Desktop.
- Podman installer.
- Operating system specific installer: Brew, Chocolatey, Scoop, Winget.
- Installer for restricted environment.
Podman Desktop might fail to detect your Podman installation.
Solution
Try following steps to verify your Podman installation. After each step, quit and restart Podman Desktop to ensure that it can detect your Podman installation.
-
In a terminal, verify you can access the Podman CLI, and verify the version.
$ podman version
-
Update Podman to the latest stable version by using your installation method.
-
Search for errors in the installation logs (if your installation method is providing logs).
-
Reinstall Podman with the same installation method.
-
Reinstall Podman with the Podman Desktop installer.
-
Reinstall Podman with the Podman installer.
-
Reinstall Podman with another method.
Podman Desktop fails creating a Podman machine
Issue
Podman Desktop might fail creating a Podman machine.
Workaround
-
In a terminal, create the Podman machine with the Podman CLI:
$ podman machine init
-
If the creation fails, read the logs carefully to continue troubleshooting.
Podman Desktop fails starting a Podman machine
Issue
Podman Desktop might fail starting a Podman machine.
Workaround
-
In a terminal, start the Podman machine with the Podman CLI:
$ podman machine start
-
If the creation fails, read the logs carefully to continue troubleshooting.
Podman Desktop fails listing images or containers
Podman Desktop might fail listing images or container.
Prerequisites
- Podman 4.1.0 or later is needed. Podman Desktop requires the Podman machine to expose the socket on the host for macOS, and on a named pipe for Windows
Procedure
-
On Windows and macOS: in a terminal, verify that at least one Podman machine is running:
$ podman machine list
-
To verify you can connect by using the CLI, in a terminal, run the
hello
container:$ podman run quay.io/podman/hello
Podman Desktop fails listing containers
Issue
Podman Desktop might display "No Containers" as shown below, even if there are active containers running in the background.
Solution
-
Stop and restart Podman Desktop.
-
In Podman Desktop, restart the Podman machine.
-
In a terminal, restart the Podman machine:
$ podman machine stop
$ podman machine start -
If the previous step did not work for you, delete your Podman machine, and create a new one:
$ podman machine rm
$ podman machine init -
If the previous steps did not work for you, delete your Podman configuration files, and create a new Podman machine:
$ rm -rf ~/.local/share/containers/podman
$ rm -rf ~/.config/containers/
$ podman machine init
Podman Desktop is failing to display the images or containers from a rootful Podman machine
The rootful configuration for a Podman machine depends on the Podman machine default connection. The default connection can be modified by external events, or when creating a new Podman machine. Podman Desktop might then reconnect in rootless mode, and fail to display the images or containers.
Workaround
-
Verify that the Podman default connection is the rootful connection to your Podman machine:
$ podman system connection ls
The default connection has
true
at the end of the line.The rootful connection has a
-root
name suffix, and assh://root@
URI prefix.Example default rootful connection:
Name URI Identity Default
podman-machine-default ssh://user@127.0.0.1:54826/run/user/1000/podman/podman.sock c:\Users\username\.ssh\podman-machine-default false
podman-machine-default-root ssh://root@127.0.0.1:54826/run/podman/podman.sock c:\Users\username\.ssh\podman-machine-default trueExample default rootless connection:
Name URI Identity Default
podman-machine-default ssh://user@127.0.0.1:54826/run/user/1000/podman/podman.sock c:\Users\username\.ssh\podman-machine-default true
podman-machine-default-root ssh://root@127.0.0.1:54826/run/podman/podman.sock c:\Users\username\.ssh\podman-machine-default falseContinue with the next steps only if the default connection is not the rootful connection to your Podman machine.
-
Set the Podman machine in rootful mode:
$ podman machine set --rootful
-
Restart the Podman machine:
$ podman machine stop
$ podman machine start -
Verify that Podman default connection points to the rootful connection:
$ podman system connection ls
Continue with the next steps only if the default connection is not the rootful connection to your Podman machine.
-
Set the Podman machine, such as
podman-machine-default
in rootful mode:$ podman system connection default podman-machine-default-root
-
Restart the Podman machine:
$ podman machine stop
$ podman machine start
Verification
-
The Podman default connection is the rootful connection to your Podman machine:
$ podman system connection ls
Warning about Docker compatibility mode
Issue
When running the Podman provider, a warning shows regarding Docker compatibility mode on the dashboard:
⚠️ Docker Socket Compatibility: Podman is not emulating the default Docker socket path: '/var/run/docker.sock'. Docker-specific tools may not work. See troubleshooting page on podman-desktop.io for more information.
This might appear when either:
- The Docker socket is not mounted correctly.
- Docker Desktop is also being ran at the same time.
Solution
-
Stop Docker Desktop (if installed).
-
On macOS, Run the
podman-mac-helper
binary:$ sudo podman-mac-helper install
-
Restart the Podman machine to recreate and activate the default Docker socket path.
Note: If Docker Desktop is started again, it will automatically re-alias the default Docker socket location and the Podman compatibility warning will re-appear.