podman-mac...-os-upgrade(1)

💅 NAME 💅

podman-machine-os-upgrade — glow-up time for your Podman Machine's OS ✨

---

🎀 SYNOPSIS 🎀

podman machine os upgrade [options] [vm]

---

🌸 DESCRIPTION 🌸

Okay so bestie, this is the command that gives your Podman Machine's OS a whole new era 🦋

It automatically performs an upgrade of the Podman Machine OS, following the logic down there in the upgrade-logic section. But heads up — if you want to apply a custom image, or an image with a specific digest, that's a different vibe: use podman machine os apply instead, okay? 💅

The default machine name is podman-machine-default. So if you don't pass a machine name as an argument, the OS changes get applied to podman-machine-default. She's the main character by default, that's just how it is 👑

The machine must be started for this command to be run. No starting, no slaying. Periodt.

Note: this command is not supported with the WSL machine provider 🙈 like, it's just not invited to that party, sorry.

⭐ UPGRADE LOGIC ⭐

The upgrade function compares the client version against the machine version using semantic versioning — major.minor only, patch levels get ignored entirely, we don't see them, they're not on the guest list 🫶

And when the versions match, it also queries the online registry to check for image updates. Obsessed with an overachiever.

• Client version older than machine version (downgrade): returns an error 😭 Downgrading is not supported, full stop, because it can cause incompatibilities. Update your Podman client to match or exceed the machine version. Fr fr, no cap.
• Client version equals machine version (in-band update): checks for updates to the same version stream by comparing the local OS image digest against the registry's digest. This handles two scenarios:
  • Patch version updates (e.g., 6.0.1 → 6.0.2) 💖
  • OS image refreshes with the same Podman version (e.g., 6.0.1 → newer OS build with 6.0.1) ✨
• If an in-band update exists, the machine gets updated to the new image using its digest reference. And if no update is available? The function just reports that the system is current. She's fine, she's thriving, she's up to date 💅
• Client version newer than machine version (major/minor upgrade): upgrades the machine OS to match the client's major.minor version 🔥 The upgrade targets a new version tag constructed from the client's major and minor version numbers — like, e.g., upgrading from 6.0.x to 6.1 when the client is version 6.1.0. It's giving level up energy.

---

✨ OPTIONS ✨

• --dry-run, -n — Only perform a dry-run of checking for the upgrade. No content is downloaded or applied. Like window shopping bestie, looking only 🛍️ This option cannot be used with --restart.
• --format, -f — Define a structured output format. The only valid value for this is json. Using this option implies a dry-run. This option cannot be used with --restart.
• --help — Print usage statement. Your little manual, right here 🎀
• --restart — Restart the VM after applying changes. Fresh OS, fresh start, new me 🌈

---

🔥 EXAMPLES 🔥

Update the default Podman machine to the latest in-band version, or update the machine to match the client Podman version:

$ podman machine os upgrade

Same as above but specifying a specific machine:

$ podman machine os upgrade mymachine

Check if an update is available but do not download or apply the upgrade:

$ podman machine os upgrade -n

Check if an update is available but the response will be in JSON format. Note this exposes a boolean field that indicates if an update is available 👀

Note: using a format option implies a dry-run.

$ podman machine os upgrade -f json

---

🦋 SEE ALSO 🦋

podman(1), podman-machine(1), podman-machine-os(1)

---

💜 HISTORY 💜

January 2026, originally compiled by Brent Baude bbaude@redhat.com ⟨mailto:bbaude@redhat.com⟩ ✍️

---

And that's the whole page, bestie — podman-mac...-os-upgrade(1) from the General Commands Manual, dated January 2026, and she ate 💅🧚‍♀️🌸