podman machine: Podman on macOS and Windows
podman machine creates and controls the lightweight Linux VM that runs containers on macOS and Windows.
Podman runs Linux containers, so on macOS and Windows it needs a VM. podman machine manages that VM, which matters for non-Linux CI runners.
What it does
podman machine initializes, starts, stops, and removes the managed Linux VM (backed by QEMU/applehv on macOS or WSL on Windows) where containers actually run. The podman CLI on the host forwards commands into this VM over a connection.
Common usage
podman machine init
podman machine start
podman machine list
podman machine ssh
# a rootful machine for workloads needing root
podman machine init --rootfulOptions
| Command/Flag | What it does |
|---|---|
| init | Create a new VM |
| start / stop | Boot or shut down the VM |
| list | Show configured machines and their state |
| ssh | Open a shell inside the VM |
| --rootful | Run the VM Podman as root |
| --cpus / --memory / --disk-size | Size the VM resources |
In CI
On Linux runners (the common case) you do not use podman machine at all; Podman runs natively. On macOS runners, podman machine init && podman machine start must run before any container command, and the first init downloads an image so allow time and disk for it.
Common errors in CI
"Error: vm \"podman-machine-default\" does not exist" means podman machine init was never run. "Cannot connect to Podman ... is the Podman service running?" means the machine is stopped; podman machine start. On macOS runners, an init that fails on disk space or virtualization support means the runner lacks the resources or the hypervisor; on Linux, this whole class of error does not apply.