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.
- Requirements
- Get the source code
- Build and test the Podman client for Windows
- Build and test the Podman Windows installer
- Validate changes before submitting a PR
This documentation assumes one uses a Windows 10 or 11 development machine and a PowerShell terminal.
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 is used to generate Podman documentation. It is
required for building the documentation and the
bundle installer. It can be avoided when building and
testing the
Podman client for Windows or
the standalone podman.msi
installer.
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).
.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
The installer includes a C program that checks the installation of the pre-required virtualization providers (WSL or Hyper-V). Building this program requires the Microsoft C/C++ compiler and the PowerShell Module VSSetup:
- Download the Build Tools for Visual Studio 2022 installer
Invoke-WebRequest -Uri 'https://aka.ms/vs/17/release/vs_BuildTools.exe' -OutFile "$env:TEMP\vs_BuildTools.exe"
- Run the installer with the parameter to include the optional C/C++ Tools
& "$env:TEMP\vs_BuildTools.exe" --passive --wait `
--add Microsoft.VisualStudio.Workload.VCTools `
--includeRecommended `
--remove Microsoft.VisualStudio.Component.VC.CMake.Project
- Install the PowerShell Module VSSetup
Install-Module VSSetup
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 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 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 %PROGRAMDATA%/containers/containers.conf
.
More on that later.
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.
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.
The following steps describe how to build the podman.exe
binary from sources
and test it.
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
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
To test some particular configurations of Podman, create a containers.conf
file:
New-Item -ItemType Directory $env:PROGRAMDATA\containers\
New-Item -ItemType File $env:PROGRAMDATA\containers\containers.conf
notepad $env:PROGRAMDATA\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.
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.
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.
The Podman Windows installer (e.g., podman-5.1.0-dev-setup.exe
) is a bundle
that includes an msi package (podman.msi
) and installs the WSL kernel
(podman-wslkerninst.exe
). It's built using the
WiX Toolset and the
PanelSwWixExtension
WiX extension. The source code is in the folder contrib\win-installer
.
To build the installation bundle, run the following command:
.\winmake.ps1 installer
ℹ️ making podman-remote
, win-gvproxy
, and docs
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.2.0-dev-setup.exe
.
The installer
target of winmake.ps1
runs the script
contrib\win-installer\build.ps1
that, in turns, executes:
build-hooks.bat
: buildspodman-wslkerninst.exe
(WSL kernel installer) andpodman-msihooks.dll
(helper that checks if WSL and Hyper-V are installed).dotnet build podman.wixproj
: buildspodman.msi
from the WiX source filespodman.wxs
,pages.wxs
,podman-ui.wxs
andwelcome-install-dlg.wxs
.dotnet build podman-setup.wixproj
: buildspodman-setup.exe
file from WiX Burn bundleburn.wxs
.
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:
contrib\win-installer\podman-5.1.0-dev-setup.exe /install /log podman-setup.log
It generates the files podman-setup.log
and podman-setup_000_Setup.log
,
which include detailed installation information, in the current directory.
Run it in quiet
mode to automate the installation and avoid interacting with
the GUI. Open the terminal as an administrator, add the /quiet
option, and
set the bundle variables MachineProvider
(wsl
or hyperv
), WSLCheckbox
(1
to install WSL as part of the installation, 0
otherwise), and
HyperVCheckbox
(1
to install Hyper-V as part of the installation, 0
otherwise):
contrib\win-installer\podman-5.1.0-dev-setup.exe /install `
/log podman-setup.log /quiet `
MachineProvider=wsl WSLCheckbox=0 HyperVCheckbox=0
The following command executes a number of tests of the windows installer. Running it requires an administrator terminal.
.\winmake.ps1 installertest
Building and testing the standalone podman.msi
package during development may
be useful. Even if this package is not published as a standalone file when
Podman is released (it's included in the podman-setup.exe
bundle), it can be
faster to build and test that rather than the full bundle during the development
phase.
Run the command dotnet build
to build the standalone podman.msi
file:
Push-Location .\contrib\win-installer\
dotnet build podman.wixproj /property:DefineConstants="VERSION=9.9.9" -o .
Pop-Location
It creates the file .\contrib\win-installer\en-US\podman.msi
. Test it using the
Microsoft Standard Installer
command line tool:
msiexec /package contrib\win-installer\en-US\podman.msi /l*v podman-msi.log
To run it in quiet, non-interactive mode, open the terminal as an
administrator, add the /quiet
option, and set the MSI properties
MACHINE_PROVIDER
(wsl
or hyperv
), WITH_WSL
(1
to install WSL as part
of the installation, 0
otherwise) and WITH_HYPERV
(1
to install Hyper-V as
part of the installation, 0
otherwise):
msiexec /package contrib\win-installer\en-US\podman.msi /l*v podman-msi.log /quiet MACHINE_PROVIDER=wsl WITH_WSL=0 WITH_HYPERV=0
ℹ️ podman.msi
GUI dialogs, defined in the file
contrib\win-installer\welcome-install-dlg.wxs
, are distinct from the installation bundle
podman-setup.exe
GUI dialogs, defined in
contrib\win-installer\podman-theme.xml
.
Inspect the msi installation log podman-msi.log
(or
podman-setup_000_Setup.log
if testing with the bundle) to verify that the
installation was successful:
Select-String -Path "podman-msi.log" -Pattern "Installation success or error status: 0"
These commands too are helpful to check the installation:
# Check the copy of the podman client in the Podman folder
Test-Path -Path "$ENV:PROGRAMFILES\RedHat\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\Red Hat\Podman"
Get-ItemProperty "HKLM:\SOFTWARE\Red Hat\Podman" InstallDir
# Check the 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.
Podman can be uninstalled from the Windows Control Panel or running the following command from a terminal as an administrator:
contrib\win-installer\podman-5.1.0-dev-setup.exe /uninstall /quiet /log podman-setup-uninstall.log
The uninstaller does not delete some folders. Clean them up manually:
$extraFolders = @(
"$ENV:PROGRAMDATA\containers\"
"$ENV:LOCALAPPDATA\containers\"
"$env:USERPROFILE.config\containers\"
"$env:USERPROFILE.local\share\containers\"
)
$extraFolders | ForEach-Object {Remove-Item -Recurse -Force $PSItem}
The following commands are helpful to verify that the uninstallation was successful:
# Inspect the uninstallation log for a success message
Select-String -Path "podman-setup-uninstall_000_Setup.log" -Pattern "Removal success or error status: 0"
# Check that the uninstaller removed Podman resources
$foldersToCheck = @(
"$ENV:PROGRAMFILES\RedHat\Podman\podman.exe"
"HKLM:\SOFTWARE\Red Hat\Podman"
"$ENV:PROGRAMDATA\containers\"
"$env:USERPROFILE.config\containers\"
"$env:USERPROFILE.local\share\containers\"
"$ENV:LOCALAPPDATA\containers\"
"$ENV:PROGRAMDATA\containers\containers.conf.d\99-podman-machine-provider.conf"
)
$foldersToCheck | ForEach-Object {Test-Path -Path $PSItem}
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.
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
.
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 lint
. Configure the Podman machine with at least 4GB of memory:
podman machine init -m 4096
.