Troubleshooting Podman on Windows
You can find here troubleshooting help for issues specific to Windows.
Deleting a corrupted Podman Machine
Issue
-
You are not able to stop your Podman Machine.
$ podman machine stop
-
The Logs contain this error:
Error: Error stopping sysd: exit status 1
Workaround
-
To display the active Windows Subsystem for Linux (WSL) distribution list: in the terminal, run:
$ wsl --list
-
The command returns the list of active WSL distributions. Identify your Podman Machine in the list, such as
podman-machine-default
. -
To stop, and uninstall your Podman Machine: in the terminal, replace
podman-machine-default
by your Podman machine name, and run:$ wsl --unregister podman-machine-default
Additional resources
The terminal session attaches to Podman Desktop when launching it from the command line
Issue
- When you start Podman Desktop from the command line in Windows the terminal session attaches to it.
- When you quit the terminal, it kills Podman Desktop.
Workaround
- Set the environment variable
ELECTRON_NO_ATTACH_CONSOLE
to true before launching Podman Desktop.
When the host is behind a VPN, Podman cannot access network resources
When the host is behind a VPN, Podman might fail to access network resources, and display errors such as Temporary failure in name resolution.
Solution
See Accessing resources behind a VPN with Podman on Windows.
Older WSL versions might lead to networking issues
Older versions of WSL might cause networking issues, such as the Get-NetTCPConnection
error, indicating that the WSL loopback forwarding facility is not functioning correctly. Recent versions of WSL do not have this issue.
Solution
-
Update Windows to either the 21H1, 21H2, or 22H2 version of Windows 10, or to the 21H1 version of Windows 11, or greater.
-
Update WSL:
wsl --update
-
Optionally, delete your Podman machine, and create a new one.
Windows 10 Enterprise LTSC version 21H2: Podman Desktop is unable to detect WSL2 machine
On a Windows 10 LTSC version, running the wsl --install --no-distribution
command does not work, and the Podman Desktop setup does not run smoothly.
You must install a specific Windows Subsystem for Linux (WSL) distribution to make the Podman Desktop setup run smoothly. After setting up Podman Desktop, you can unintsall the WSL distribution.
Solution: Enable Podman Desktop setup to run smoothly
Windows 11 or later version
- Run the
wsl --update
command to update the WSL kernel. - Run the
wsl --install --no-distribution
command to not install any WSL distribution. - Restart your machine.
Windows 10 LTSC version
- Run the
wsl --update
command. - Run the
wsl --install -d <distro>
command to install a specific WSL distribution.- Replace
distro
with any official WSL distribution, such asubuntu-24.04
.
- Replace
- Restart your machine.
- (Optional): Run the
wsl --unregister <distro>
to uninstall the WSL distribution.
Unable to install Compose extension 2.33.x on Windows due to certificate signature failure
Installing the Compose extension version 2.33.x fails, and you receive an error message: Unable to fetch the available extensions: certificate signature failure
.
Workaround
The reason for the failure could be that the Windows Certificate Store has been improperly loaded with the corporate certificate chain. Usually, all the certificates are placed in one location, namely TrustedRootCA, which results in the failure to import the certificates into the Podman Desktop application.
To get root CA self-signed certificates to work, you can identify where these certificates have been placed in the Windows Certificate Store. Then, you can clean the Store to ensure those certificates are in their proper locations.