podman-system-migrate(1)

🌸 podman-system-migrate(1) — your girl's guide to the migration glow-up ✨

okay so real talk, bestie: this page lives in the General Commands Manual, and its name is podman-system-migrate. Say it with me. We're moving your containers to a whole new podman era and honestly? It's giving self-care. 🫶

---

🦋 NAME

podman-system-migrate — migrate existing containers to a new podman version ✨

---

🎀 SYNOPSIS

podman system migrate [options]

---

💅 DESCRIPTION

podman system migrate migrates containers to the latest podman version. Like, that's the whole vibe. 💖

It takes care of migrating your existing containers to the latest version of podman if any change is necessary. No cap — if something needs to move, this is what moves it.

"Rootless Podman uses a pause process to keep the unprivileged namespaces alive. ⏸️ That pause process is lowkey a vibe-keeper, and it prevents any change to the /etc/subuid and /etc/subgid files from being propagated to the rootless containers while the pause process is running. Like, the changes literally cannot get through. 🚧

For these changes to be propagated, it is necessary to first stop all running containers associated with the user and to also stop the pause process and delete its pid file. Yeah, all of that. 😮‍💨 Instead of doing it manually, podman system migrate can be used to stop both the running containers and the pause process. Then the /etc/subuid and /etc/subgid files can be edited or changed with usermod to recreate the user namespace with the newly configured mappings. Slay. 💫

Not me quoting that paragraph with the quotation mark still attached — that's how it is in the original, bestie, I don't make the rules. 🙈

---

✨ OPTIONS ✨

🗄️ --migrate-db

Migrate from the legacy BoltDB database to SQLite. 🧚 Big move.

Support for BoltDB has been removed in Podman 6.0, and existing BoltDB databases must be migrated to continue using the containers, pods, and volumes stored in them. So like… you don't really have a choice, but it's for your own good. 💅

This is also done automatically on system reboot. Migrating as part of a reboot is generally preferred as there is less potential for race conditions caused by other Podman processes running at the same time. 🔥 Reboot = the calm, cute, no-chaos option.

If a migration is necessary, Podman will fail to run with a descriptive error indicating this command must be used or the system must be rebooted. Very "read the room" of it. 💀

To ensure complete migration, all other Podman commands should be shut down before database migration. 👑 In particular, systemd-activated services like podman system service and Quadlets should be manually stopped prior to migration. Like, actually stop them, don't just hope.

The legacy database will not be removed, so no data loss should occur even on failure. 🫶 Comforting, right? That's the good part.

🏃 --new-runtime=runtime

Set a new OCI runtime for all containers. 🌈

This can be used after a system upgrade which changes the default OCI runtime to move all containers to the new runtime. There are no guarantees that the containers continue to work under the new runtime, as some runtimes support differing options and configurations. 😭 So like, it might be iconic, it might be a whole thing. Fr fr, know that going in.

---

🍓 EXAMPLES

Normal invocation 💖

### No output is expected from this command.
$ podman system migrate

No output. None. That's not it being broken, that's it being perfect. ⭐

Migration to a new OCI runtime (e.g., from crun to runc) 🔥

### Create a container using the current default runtime (e.g., crun)
$ podman create --name test-alpine alpine

### Confirm the current runtime
$ podman container inspect test-alpine | grep OCIRuntime
          "OCIRuntime": "crun",

### Migrate all containers to use a new runtime (e.g., runc)
$ podman system migrate --new-runtime runc

### Verify the container is now using the new runtime
$ podman container inspect test-alpine | grep OCIRuntime
          "OCIRuntime": "runc",

Look at it switching runtimes like a main character changing outfits. 👑💅

---

🌸 SEE ALSO

podman(1), podman-system(1), usermod(8) — go read those too, iykyk 💜

---

🎀 HISTORY

April 2019, Originally compiled by Giuseppe Scrivano (gscrivan at redhat dot com). An icon. 🙌

---

💖 okay that's the whole page!! this one's podman-system-migrate(1) from the General Commands Manual, dated April 2019 in its history. bye bestie, go migrate something responsibly 🦋✨💜