# podman machine: Podman on macOS and Windows

> podman machine manages the Linux VM Podman uses on macOS and Windows. Reference for init, start, the rootful flag, and the VM errors in CI.

Source: https://latchkey.dev/learn/command-reference/podman-machine  
Updated: 2026-06-30

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

```Terminal
podman machine init
podman machine start
podman machine list
podman machine ssh
# a rootful machine for workloads needing root
podman machine init --rootful
```

## Options

| 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.

## FAQ

### podman machine: Podman 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.

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt