podman/build_windows.md

Building the Podman client and client installer on Windows

The following describes the process for building and testing the Podman Windows client (podman.exe) and the Podman Windows installer (podman-setup.exe) on Windows.

Topics

• Requirements
  • OS requirements
  • Git and go
  • Pandoc (optional)
  • .NET SDK
  • Virtualization Provider
    • WSL
    • Hyper-V
• Get the source code
  • Allow local PowerShell scripts execution
• Build and test the Podman client for Windows
  • Build the Podman client
  • Download gvproxy.exe and win-sshproxy.exe
  • Create a configuration file (optional)
  • Create and start a podman machine
  • Run a container using podman
• Build and test the Podman Windows installer
  • Build the Windows installer
  • Test the Windows installer
    • Run the Windows installer automated tests
    • Verify the installation
  • Uninstall and clean-up
    • Retrieve Podman installed products
• Validate changes before submitting a PR
  • winmake lint
  • winmake validatepr

Requirements

OS requirements

This documentation assumes one uses a Windows 10 or 11 development machine and a PowerShell terminal.

Git and go

To build Podman, the git and go tools are required. In case they are not yet installed, open a Windows PowerShell terminal and run the following command (it assumes that winget is installed):

winget install -e GoLang.Go Git.Git

ℹ️ A terminal restart is advised for the PATH to be reloaded. This can also be manually changed by configuring the PATH:

$env:Path += ";C:\Program Files\Go\bin\;C:\Program Files\Git\cmd\"

Pandoc (optional)

Pandoc is used to generate Podman documentation. It is used for building the documentation. Pandoc can be installed from https://pandoc.org/installing.html. When performing the Pandoc installation one, has to choose the option "Install for all users" (to put the binaries into "Program Files" directory). Alternatively, Podman documentation can be built using a container with the target docs-using-podman in the winmake.ps1 script.

.\winmake docs-using-podman

.NET SDK

.NET SDK, version 6 or later, is required to develop and build the Podman Windows installer. It's not required for the Podman Windows client.

winget install -e Microsoft.DotNet.SDK.8

WiX Toolset v5, distributed as a .NET SDK tool, is used too and can be installed using dotnet install:

dotnet tool install --global wix --version 5.0.2

ℹ️ Because WiX Toolset has changed its licensing model when v6 was released, Podman still uses the WiX Toolset v5.0.2 and we recommend using it as well for local development (although it's not strictly required).

Virtualization Provider

Running Podman on Windows requires a virtualization provider. The supported providers are the Windows Subsystem for Linux (WSL) and Hyper-V. At least one of those two is required to test podman on a local Windows machine.

WSL

WSL can be installed on Windows 10 and Windows 11, including Windows Home, with the following command, from a PowerShell or Windows Command Prompt terminal in administrator mode:

wsl --install

For more information refer to the official documentation.

Hyper-V

Hyper-V is an optional feature of Windows Enterprise, Pro, or Education (not Home). It is available on Windows 10 and 11 only and has some particular requirements in terms of CPU and memory. To enable it on a supported system, enter the following command:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

After running this command, a restart of the Windows machine is required.

ℹ️ Configure the VM provider used by podman (Hyper-V or WSL) in the file %APPDATA%/containers/containers.conf. More on that later.

Get the source code

Open a Windows Terminal and run the following command:

git config --global core.autocrlf false

It configures git so that it does not automatically convert LF to CRLF. In the Podman git repository, files are expected to use Unix LF rather than Windows CRLF.

Then run the command to clone the Podman git repository:

git clone https://github.com/containers/podman

It creates the folder podman in the current directory and clones the Podman git repository into it.

Allow local PowerShell scripts execution

A developer can build the Podman client for Windows and the Windows installer with the PowerShell script winmake.ps1.

Windows sets the ExecutionPolicy to Restricted by default; running scripts is prohibited. Determine the ExecutionPolicy on the machine with this command:

Get-ExecutionPolicy

If the command returns Restricted, the ExecutionPolicy should be changed to RemoteSigned:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

This policy allows the execution of local PowerShell scripts, such as winmake.ps1, for the current user.

Build and test the Podman client for Windows

The following steps describe how to build the podman.exe binary from sources and test it.

Build the Podman client

Open a PowerShell terminal and move to Podman local git repository directory:

Set-Location .\podman

Build podman.exe

.\winmake.ps1 podman-remote

ℹ️ Verify build's success by checking the content of the .\bin\windows folder. Upon successful completion, the executable podman.exe should be there:

Get-ChildItem .\bin\windows\


    Directory: C:\Users\mario\Git\podman\bin\windows


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----         2/27/2024  11:59 AM       45408256 podman.exe

Download gvproxy.exe and win-sshproxy.exe

gvisor-tap-vsock binaries (gvproxy-windowsgui.exe and win-sshproxy.exe) are required to run the Podman client on Windows. The executables are expected to be in the same folder as podman.exe. The following command downloads the latest version in the .\bin\windows\ folder:

.\winmake.ps1 win-gvproxy

ℹ️ To verify that the binaries have been downloaded successfully, check the content of the .\bin\windows` folder.

Get-ChildItem .\bin\windows\


    Directory: C:\Users\mario\Git\podman\bin\windows


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----         2/29/2024  12:10 PM       10946048 gvproxy.exe
-a----         2/27/2024  11:59 AM       45408256 podman.exe
-a----         2/29/2024  12:10 PM        4089856 win-sshproxy.exe

Create a configuration file (optional)

To test some particular configurations of Podman, create a containers.conf file:

New-Item -ItemType Directory $env:APPDATA\containers\
New-Item -ItemType File $env:APPDATA\containers\containers.conf
notepad $env:APPDATA\containers\containers.conf

For example, to test with Hyper-V as the virtualization provider, use the following content:

[machine]
provider="hyperv"

Find the complete list of configuration options in the documentation.

Create and start a podman machine

Execute the following commands in a terminal to create a Podman machine:

.\bin\windows\podman.exe machine init

When machine init completes, run machine start:

.\bin\windows\podman.exe machine start

ℹ️ If the virtualization provider is Hyperv-V, execute the above commands in an administrator terminal.

Run a container using podman

Use the locally built Podman client for Windows to run containers:

.\bin\windows\podman.exe run hello-world

To learn how to use the Podman client, refer to its tutorial.

Build and test the Podman Windows installer

The Podman Windows installer (e.g., podman-5.7.0.msi) is an MSI package built using the WiX Toolset v5. The installer supports installation at both user scope (per-user) and machine scope (per-machine/administrator). The source code is in the folder contrib\win-installer.

Build the Windows installer

To build the MSI installer, run the following command:

.\winmake.ps1 installer

ℹ️ making podman-remote, win-gvproxy, and docs (or docs-using-podman) is required before running this command.

Locate the installer in the contrib\win-installer folder (relative to checkout root) with a name like podman-5.7.0.msi, where 5.7.0 is the version of Podman on the local branch.

The installer target of winmake.ps1 runs the script contrib\win-installer\build.ps1 that, in turn, executes:

• dotnet build podman.wixproj: builds podman.msi from the WiX source files wix\podman-main.wxs, wix\podman-ui-main.wxs, and wix\podman-ui-welcome-dlg.wxs.

Test the Windows installer

Double-click on the Windows installer to run it. To get the installation logs with debug information, running it via the command line is recommended:

msiexec /package contrib\win-installer\podman-5.7.0.msi /l*v podman-msi.log

It generates the file podman-msi.log, which includes detailed installation information, in the current directory.

The MSI installer supports both user-scope and machine-scope installations:

• User scope (per-user): No administrator privileges required. Files are installed in the user's profile directory, and the PATH is updated only for the current user. This is the default scope.

• Machine scope (per-machine): Requires administrator privileges. Files are installed in Program Files, and the PATH is updated for all users.

To run an automated installation in quiet, non-interactive mode and set the machine provider (wsl or hyperv), use the following command:

User scope installation (no administrator required):

msiexec /package contrib\win-installer\podman-5.7.0.msi /l*v podman-msi.log `
        /quiet MSIINSTALLPERUSER=1 MACHINE_PROVIDER=wsl

Machine scope installation (requires administrator terminal):

msiexec /package contrib\win-installer\podman-5.7.0.msi /l*v podman-msi.log `
        /quiet ALLUSERS=1 MACHINE_PROVIDER=wsl

ℹ️ If uninstallation fails, the installer may end up in an inconsistent state. Podman results as uninstalled, but the MSI package is still tracked in the Windows registry and will affect further attempts to reinstall Podman. When this is the case, trying to reinstall Podman results in the installer returning zero (success) but no action is executed. The package GUID can be found in the installation logs:

Product: Podman CLI -- Installation completed successfully.
ProductCode: {<GUID>}

To fix this problem, remove the tracked package:

msiexec /x "{<GUID>}"

Run the Windows installer automated tests

The following command executes a number of tests of the windows installer. Running it requires an administrator terminal.

.\winmake.ps1 installertest [wsl|hyperv]

Verify the installation

Inspect the MSI installation log podman-msi.log to verify that the installation was successful:

Select-String -Path "podman-msi.log" -Pattern "Installation success or error status: 0"

The following commands are helpful to check the installation:

For machine scope (per-machine) installations:

# Check the copy of the podman client in the Podman folder
Test-Path -Path "$ENV:PROGRAMFILES\Podman\podman.exe"
# Check the generation of the podman configuration file
Test-Path -Path "$ENV:PROGRAMDATA\containers\containers.conf.d\99-podman-machine-provider.conf"
# Check that the installer configured the right provider
Get-Content "$ENV:PROGRAMDATA\containers\containers.conf.d\99-podman-machine-provider.conf" | Select -Skip 1 | ConvertFrom-StringData | % { $_.provider }
# Check the creation of the registry key
Test-Path -Path "HKLM:\SOFTWARE\Podman"
Get-ItemProperty "HKLM:\SOFTWARE\Podman" InstallDir
# Check that podman.exe is in the $PATH
$env:PATH | Select-String -Pattern "Podman"

For user scope (per-user) installations:

# Check the copy of the podman client in the Podman folder
Test-Path -Path "$ENV:LOCALAPPDATA\Programs\Podman\podman.exe"
# Check the generation of the podman configuration file
Test-Path -Path "$ENV:APPDATA\containers\containers.conf.d\99-podman-machine-provider.conf"
# Check that the installer configured the right provider
Get-Content "$ENV:APPDATA\containers\containers.conf.d\99-podman-machine-provider.conf" | Select -Skip 1 | ConvertFrom-StringData | % { $_.provider }
# Check the creation of the registry key
Test-Path -Path "HKCU:\SOFTWARE\Podman"
Get-ItemProperty "HKCU:\SOFTWARE\Podman" InstallDir
# Check that podman.exe is in the $PATH
$env:PATH | Select-String -Pattern "Podman"

ℹ️ Podman CI uses script contrib\cirrus\win-installer-main.ps1. Use it locally, too, to build and test the installer:

$ENV:CONTAINERS_MACHINE_PROVIDER='wsl'; .\contrib\cirrus\win-installer-main.ps1
$ENV:CONTAINERS_MACHINE_PROVIDER='hyperv'; .\contrib\cirrus\win-installer-main.ps1

Uninstall and clean-up

Podman can be uninstalled from the Windows Control Panel or using the MSI uninstall command. Administrator privileges will be required if Podman was installed for the machine, rather than for a user:

msiexec /x contrib\win-installer\podman-5.7.0.msi /quiet /l*v podman-msi-uninstall.log

The uninstaller does not delete some folders. Clean them up manually:

For machine scope installations:

$extraFolders = @(
    "$ENV:PROGRAMDATA\containers\"
    "$ENV:LOCALAPPDATA\containers\"
    "$env:USERPROFILE\.config\containers\"
    "$env:USERPROFILE\.local\share\containers\"
)
$extraFolders | ForEach-Object {Remove-Item -Recurse -Force $PSItem -ErrorAction SilentlyContinue}

For user scope installations:

$extraFolders = @(
    "$ENV:APPDATA\containers\"
    "$ENV:LOCALAPPDATA\containers\"
    "$env:USERPROFILE\.config\containers\"
    "$env:USERPROFILE\.local\share\containers\"
)
$extraFolders | ForEach-Object {Remove-Item -Recurse -Force $PSItem -ErrorAction SilentlyContinue}

The following commands are helpful to verify that the uninstallation was successful:

For machine scope installations:

# Inspect the uninstallation log for a success message
Select-String -Path "podman-msi-uninstall.log" -Pattern "Removal success or error status: 0"
# Check that the uninstaller removed Podman resources
$foldersToCheck = @(
    "$ENV:PROGRAMFILES\Podman\podman.exe"
    "HKLM:\SOFTWARE\Podman"
    "$ENV:PROGRAMDATA\containers\"
    "$env:USERPROFILE\.config\containers\"
    "$env:USERPROFILE\.local\share\containers\"
    "$ENV:APPDATA\containers\"
    "$ENV:PROGRAMDATA\containers\containers.conf.d\99-podman-machine-provider.conf"
)
$foldersToCheck | ForEach-Object {Test-Path -Path $PSItem}

For user scope installations:

# Inspect the uninstallation log for a success message
Select-String -Path "podman-msi-uninstall.log" -Pattern "Removal success or error status: 0"
# Check that the uninstaller removed Podman resources
$foldersToCheck = @(
    "$ENV:PROGRAMFILES\Podman\podman.exe"
    "HKCU:\SOFTWARE\Podman"
    "$ENV:APPDATA\containers\"
    "$env:USERPROFILE\.config\containers\"
    "$env:USERPROFILE\.local\share\containers\"
    "$ENV:LOCALAPPDATA\containers\"
    "$ENV:APPDATA\containers\containers.conf.d\99-podman-machine-provider.conf"
)
$foldersToCheck | ForEach-Object {Test-Path -Path $PSItem}

Retrieve Podman installed products

MSI uninstallations can leave the package tracked in the Windows registry. This can cause issues when trying to reinstall Podman. The following command can be used to retrieve the package information:

$Installer = New-Object -ComObject WindowsInstaller.Installer
$InstallerProducts = $Installer.ProductsEx("", "", 7)
$InstalledProducts = ForEach($Product in $InstallerProducts){
    try {
        $ProductCode = $Product.ProductCode()
        $LocalPackage = try { $Product.InstallProperty("LocalPackage") } catch { "Unknown" }
        $VersionString = try { $Product.InstallProperty("VersionString") } catch { "Unknown" }
        $ProductName = $Product.InstallProperty("ProductName")

        [PSCustomObject]@{
            ProductCode = $ProductCode
            LocalPackage = $LocalPackage
            VersionString = $VersionString
            ProductName = $ProductName
        }
    }
    catch {
        Write-Warning "Failed to process product: $($_.Exception.Message)"
        # Skip this product and continue
        continue
    }
}
$InstalledProducts | Where-Object {$_.ProductName -match "podman"}

This command returns a list of installed Podman products:

ProductCode                            LocalPackage VersionString ProductName
-----------                            ------------ ------------- -----------
{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} Unknown      Unknown       Podman

The product code can be used to uninstall the Podman package:

msiexec /x "{<product-code>}"

Validate changes before submitting a PR

The script winmake.ps1 has a couple of targets to check the source code statically. GitHub Pull request checks execute the same statical analysis. It is highly recommended that you run them locally before submitting a PR.

winmake lint

The lint target provides a fast validation target. It runs the following tools:

• golangci-lint: runs go-specific linters configured in .golangci.yml
• pre-commit: runs more linters configured in .pre-commit-config.yaml

ℹ️ Install golangci-lint and pre-commit to run winmake.ps1 lint: pwsh winget install -e golangci-lint.golangci-lint winget install -e Python.Python.3.13 pip install pre-commit

winmake validatepr

Target validatepr performs a more exhaustive validation but takes significantly more time to complete. It uses podman to run the target .validatepr of the Linux Makefile. It builds Podman for Linux, MacOS and Windows and then performs the same checks as the lint target plus many more.

ℹ️ Create and start a Podman machine before running winmake.ps1 validatepr. Configure the Podman machine with at least 4GB of memory: podman machine init -m 4096.