10  Podman Desktop (PC Tech Install)

This chapter is written for USACE PC Techs performing a manual install of Podman Desktop on a Windows computer used by data scientists.

Context: Podman Desktop is USACE-approved, but install is not yet automated. PC Techs typically (1) copy a pre-scanned/approved installer from a centralized USACE IT folder, then (2) run the installer locally with admin rights, and (3) ensure required Windows features are enabled.

Audience
  • This page is for PC Techs (installation + system configuration).
  • Data scientists should use: Podman Desktop (Getting Started) for usage workflows after install.

10.1 What you will install / enable

  • Podman Desktop (GUI)
  • WSL2 (Windows Subsystem for Linux v2) — required backend on Windows
  • Any Windows features required for WSL2 (typically “Windows Subsystem for Linux” and “Virtual Machine Platform”)
Version policy

This guide is intentionally version-agnostic. Always use the currently pre-scanned/approved Podman Desktop installer provided through the USACE internal software distribution process.

10.2 Pre-install checklist (5 minutes)

  1. Confirm you have the approved Podman Desktop installer from the centralized IT folder.
  2. Confirm the target machine is a Windows device used for data science work.
  3. Confirm the user is expecting to use containers locally for QA/QC activities (not production hosting).
  4. Confirm you have the required admin credentials to:
    • run installers
    • enable Windows features (if needed)
    • reboot the machine (if required)

10.3 Install procedure (manual)

Step 1 — Copy installer to local machine

  1. Copy the approved Podman Desktop installer from the centralized IT folder to a local path on the target machine (example: C:\Temp\PodmanDesktop\).
  2. Verify the installer file is fully copied (size/date match expected).

Step 2 — Run the Podman Desktop installer (admin)

  1. Run the installer (use “Run as administrator” if your workflow requires it).
  2. Accept defaults unless your local IT standards require changes.
  3. Complete installation.
Reboots

WSL2 and related Windows features sometimes require a reboot to complete enablement. Plan for at least one reboot during initial setup.

10.4 WSL2 enablement / verification

Podman Desktop on Windows requires WSL2.

Step 3 — Verify WSL is available

Open PowerShell and run:

wsl --status

Expected outcomes: - If WSL is installed, you should see status output and a WSL version. - If WSL is not installed or features are missing, the command will typically provide guidance or error text.

Step 4 — Ensure WSL2 is enabled (if not already)

If WSL is not installed/enabled, use your standard Windows feature enablement process.

Typical requirements (names may vary by Windows build/policy): - Windows Subsystem for Linux - Virtual Machine Platform

After enabling features, reboot if prompted.

Step 5 — Set WSL default version to 2

wsl --set-default-version 2

Step 6 — Confirm WSL2 is working

wsl --status
wsl -l -v

Expected: - Default version: 2 - Any installed distributions show Version 2

Linux distribution (distro)

Some environments pre-provision a WSL distro; others do not. Podman Desktop may guide the user through creating/using a WSL environment when first launched.

10.5 Podman Desktop first-launch verification (PC Tech)

Step 7 — Launch Podman Desktop

  1. Launch Podman Desktop
  2. Confirm the application opens without error dialogs.

Step 8 — Verify Podman Engine is available

Within Podman Desktop: - Confirm the container engine/backend indicates it is ready/started (exact UI text varies by version). - If the UI indicates WSL2 is missing, return to the WSL2 section above.

Optional quick CLI verification (PowerShell):

podman --version
podman info

10.6 Handoff to user (what the PC Tech tells the data scientist)

Provide the user: 1. Confirmation that Podman Desktop is installed. 2. Confirmation that WSL2 is enabled. 3. Where to go next in this user guide: - Podman Desktop (Getting Started) for common workflows and QA/QC patterns.

10.7 Troubleshooting (PC Tech quick triage)

Podman Desktop opens but engine won’t start

  • Confirm WSL2 is enabled and default is version 2:
    • wsl --status
    • wsl -l -v
  • Reboot and retry.
  • If corporate virtualization policies prevent WSL2/VM features, escalate through IT channels with the error text.

wsl commands fail

  • Ensure required Windows features are enabled.
  • Ensure machine policy permits WSL2.
  • Capture:
    • full command output from wsl --status
    • Windows version/build
    • any relevant error dialogs

podman CLI not found

  • Confirm Podman Desktop installation completed successfully.
  • If PATH is managed/restricted, the CLI may not be on PATH by default—use Podman Desktop UI verification and/or reinstall per standard process.

10.8 Appendix: Copy/paste snippet for IT ticket notes (optional)

If you need to paste a concise summary into an internal IT ticket, use:

Installed Podman Desktop (approved installer from central IT folder). Verified WSL2 enabled and default set to version 2 (`wsl --status`). Verified Podman CLI responds (`podman --version`, `podman info`) and Podman Desktop launches without errors.