/
Hyper-V with Podman on Windows

Hyper-V with Podman on Windows

This article explains the installation of Hyper-V and Podman on a recent Windows.

Since WSL is ready for production use, we recommend using WSL with Podman on Windows.

For Windows related details also refer to Microsoft’s article https://learn.microsoft.com/en-us/windows-server/virtualization/hyper-v/system-requirements-for-hyper-v-on-windows.

Step 1. Activate Hyper-V

Open a PowerShell as an Administrator.

Note: The following command is only available on Windows Server Editions, on client Systems like Windows 11 use Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

This does not reboot your machine. You’ll have to reboot manually afterwards.

Execute the following comman in the PowerShell to install/enable Hyper-V:

Install-WindowsFeature -Name Hyper-V -IncludeManagementTools -Restart

This command installs/enables Hyper-V along with its management tools.

The machine will restart automatically. After the reboot, Hyper-V will be enabled.

Step 2: Podman

1. Installing Podman on Windows using Hyper-V

Note: For this setup Podman CLI Tools are needed. Podman Desktop has no relevance in the setup!

  1. Download Podman Installer from the official Podman Repository: Releases · containers/podman. (named like podman-installer-windows-amd64.exe)

  2. Run the installer and follow the instructions.

image-20250602-182032.png

  1. Once the installation is done, ensure that the environment variable for Hyper-V is set. Run the following command in PowerShell:

[System.Environment]::SetEnvironmentVariable('CONTAINERS_MACHINE_PROVIDER','hyperv')

This command gives no output, it just sets the Environment variable CONTAINERS_MACHINE_PROVIDER to hyperv.

2. Configuring Podman

Initialize a new Podman machine environment for Hyper-V in a (non-server Systems it must be a privileged) PowerShell session:

podman machine init

This will create a virtual machine within Hyper-V and download the required files. The output will include lines like:

> podman machine init Looking up Podman Machine image at quay.io/podman/machine-os:5.5 to create VM Getting image source signatures Copying blob 5df1d202925a done | Copying config 44136fa355 done | Writing manifest to image destination 5df1d202925a4f7d122c2b1e3e41f3ce4aadf20bcfef10956d27f124f0b7b8c2 Extracting compressed file: podman-machine-default-amd64.vhdx: done Machine init complete To start your machine run: podman machine start

As the last output line indicates, we can now start the prepared Podman Hyper-V environment via

podman machine start

After startup, you’ll see an output like this (this will be different if using a non-Server Windows):

Starting machine "podman-machine-default" This machine is currently configured in rootless mode. If your containers require root permissions (e.g. ports < 1024), or if you run into compatibility issues with non-podman clients, you can switch using the following command:         podman machine set --rootful API forwarding listening on: npipe:////./pipe/docker_engine Docker API clients default to this address. You do not need to set DOCKER_HOST. Machine "podman-machine-default" started successfully

Check if the connection to the VM is successful:

podman system connection list

After a system reboot, you can restart the Podman machine with the following command:

podman machine start

Within the podman-machine the runtime for Podman is executed. The podman-default-machine needs to run in order for Podman to perform its tasks. It is not sufficient, to autostart the Hyper-V machine on boot.

Troubleshooting Podman

Cannot Connect to Podman

If you enter:

podman info

and receive the following message:

OS: windows/amd64 provider: hyperv version: 5.4.2 Cannot connect to Podman. Please verify your connection to the Linux system using podman system connection list, or try podman machine init and podman machine start to manage a new Linux VM Error: unable to connect to Podman socket: failed to connect: dial tcp 127.0.0.1:62803: connectex:

Next, you need to establish a connection to the virtual machine and enable the podman.socket. To do this, open Hyper-V Manager and select the running virtual machine. Double-click it to open a terminal window. In the prompt that appears, enter the following command:

systemctl --user start podman.socket

and check the status via

systemctl --user status podman.socket

On the host VM, run the following commands to restart the Windows NAT service:

net stop winnat net start winnat

After that, restart the Podman machine. This should restore connectivity to the newly created virtual machine.

Autostarting the podman-machine-default machine

Since it is not sufficient to just autostart the HyperV Machine (since no connections to the CLI will be established), the podman machine start command needs to be executed at every startup.

Auto-Invoke podman machine start on boot

  1. Open Task Scheduler (or Aufgabenplaner in German) via the Start-Bar

  2. On the right side you can find the Create Task… Entry

  3. Enter “Start Podman Machine” as Name

  4. Enter the Configuration for “Windows 10”

  5. Select the “Triggers” Tab

  6. Choose At startup from the Begin the task menu

  7. Click the OK button

  8. Go to the Actions tab and click the New button.

  9. Enter the podman as command and machine start as arguments

  10. Accept every oncomming prompt - you may need to re-enter your password

  11. Verify podman-default-machine is running by open the HyperV-Manager

  12. Reboot

  13. Verify again, that the podman-default-machine is runing by running podman machine ls

> podman machine ls NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE podman-machine-default* hyperv 20 minutes ago Currently running 6 2GiB 100GiB