, ,

The new Hyper-V option in Podman Windows Installer

The Podman team introduced the support for Hyper-V with Podman version 4.8. With version 5.1, we updated the Podman Windows installer to allow Hyper-V configuration at installation time. This blog post will explain what this means and how to use it.

Podman Machine

Similarly to macOS, Podman on Windows requires the podman-remote client and a Linux Virtual Machine (VM) to work correctly.

The Windows installer, podman-setup.exe, installs the remote client, podman.exe, on the Windows Host. Most of the time, users don’t need to know the following details, but just in case: The remote client creates and starts the Virtual Machine with the commands podman machine init and podman machine start. After that, Podman can be used as usual to manage containers that, on Windows, run in a Linux guest Virtual Machine.

The user experience of Podman on Windows is supposed to be identical to that of Linux. Still, there are situations when the control of the Virtual Machine running Podman is needed. For instance, users may prefer a specific Virtualization provider on Windows, WSL 2, or Hyper-V, which we will discuss next.

WSL 2 and Hyper-V

There are two options for running Linux Virtual Machines on the most recent versions of Windows1 natively: the Windows Subsystem for Linux v2 (WSL 2) and Hyper-V. Both use the same underlying Windows virtualization technology, but the former uses a highly optimized subset of Hyper-V features and is considered lightweight virtualization. If you don’t know which one you should use, you will probably want WSL 2.

Use WSL 2 if…

You plan to use VMs only to run Podman machines. WSL 2 is lighter than Hyper-V and ideally suited to running containers. It is also the only supported option on the Home flavor of Windows 10 and later.

Use Hyper-V if…

You have pre-installed Hyper-V, and you plan to run VMs with a kernel other than Microsoft WSL2 Linux kernel or WSL is disabled as per your company policies.

How to run the Podman installer to use Hyper-V

The Podman v5.1 installer for Windows introduces three new command line variables:

  • MachineProvider: If set to hyperv, the installer configures Podman to use Hyper-V. If set to wsl or not set, it configures Podman to use WSL 2. 
  • HyperVCheckbox: If set to 1, the installer enables Hyper-V as part of the Podman installation. If set to 0 or not set, it doesn’t. The installer ignores this variable if the user has already installed Hyper-V.
  • SkipConfigFileCreation: If set to 1, the installation won’t create a configuration file. This variable is helpful to avoid overriding an existing configuration file when a previous version of Podman exists.

Beyond these new variables, the installer continues supporting the following ones:

  • InstallFolder: the path of the Podman installation directory. The default is C:\Program Files\RedHat\Podman.
  • WSLCheckbox: If set to 1, the installer enables WSL 2 as part of the Podman installation. If set to 0 or not set, it doesn’t. The installer ignores this variable if the user has already installed WSL 2.

For example, to install Podman and configure it to use Hyper-V, download the installation bundle from the Podman GitHub “Releases” page.  At the time of this writing, the current release is Podman v5.1.1, and the file name is podman-5.1.1-setup.exe on this release page:  https://github.com/containers/podman/releases/tag/v5.1.1. Once downloaded, run the following command from a Windows PowerShell terminal:

> .\podman-<version>-setup.exe /install MachineProvider=hyperv HyperVCheckbox=1 WSLCheckbox=0

The installation Welcome Dialog will open. Click on the “Install” button and wait for the installation completion. 

The installation requires a reboot to enable Hyper-V.

If an instance of Podman is already locally installed, the installer keeps the existing machine provider configuration.

To verify that the installation has configured Podman to use Hyper-v, look at the system-wide configuration file 99-podman-machine-provider.conf:

> Get-Content “$ENV:PROGRAMDATA\containers\containers.conf.d\99-podman-machine-provider.conf”

The next step is to start a Podman machine. To do that, open a Windows terminal as an administrator and run the following command:

> podman machine init
> podman machine start

The OS image is downloaded, and the VM is created and started. At completion, the Podman remote client is automatically configured to connect to the Podman server that runs in the Hyper-V VM. It can then be used to manage containers, pods, and images from a Windows terminal (there is no need for an Administrator terminal).

What’s coming next

Introducing the command line arguments to configure the virtualization provider is a step forward in providing the same level of support for Hyper-V as for WSL 2. But we haven’t completed the work yet. In particular, we are working on the following improvements:

  • Add a button to choose the virtualization provider on the installer welcome dialog (issue)
  • Don’t require an administrator terminal to init and start a Hyper-V based machine (issues 1 and 2)
  • When the user has already installed Hyper-V and not WSL 2, use Hyper-V as the default provider instead of WSL 2
  • Don’t ask to install WSL 2 or Hyper-V if the user has already installed it

If you have ideas on other improvements, we’d love to hear them!  Just start up a discussion in Podman’s GitHub Discussions, or join the Podman mailing list and send us a note!  To join the mailing list or discover other communication channels, checkout https://podman.io/community.

  1. Podman supports Windows 11 and Windows 10 build 19041 or higher. ↩︎

Leave a Reply


Sign up with your email address to receive updates by email from this website.