Podman Knowledge Patch

Podman knowledge patch

Use this patch before changing Podman commands, configuration, Quadlets, machine workflows, Kubernetes replay, networking, storage, image automation, or REST clients. Treat defaults, platform support, and machine-readable output as version-sensitive. Read the topic reference that matches the work instead of assuming Docker behavior or older Podman behavior.

Reference index

Breaking changes and migration hazards

Migrate BoltDB safely

• Prefer a reboot so migration runs without competing Podman processes.
• Use Podman 5.8.1 or later for migration when persistent Quadlets exist; the 5.8.0 path can leave a partial SQLite database and has no automatic recovery.
• Before podman system migrate --migrate-db, stop every other Podman process, including socket-activated services and Quadlets.
• Preserve the legacy database. Podman retains it when migration fails.
• Only move db.sql aside and retry on 5.8.1 or later when no persistent containers, pods, or volumes need to be preserved.

podman system migrate --migrate-db

Remove unsupported platform and network assumptions

For Podman 6 deployments, require Linux kernel 5.2 or newer and migrate away from:

• Intel macOS hosts and Windows 10;
• cgroups v1 for the engine;
• iptables networking and CNI;
• slirp4netns and its removed global --network-cmd-path option.

Use cgroups v2, nftables, Netavark, and Pasta as applicable. Pair Podman 6 with Buildah 1.44.0, Skopeo 1.23, Netavark and Aardvark 2.0.0, and containers/common configuration 0.68.0. A Podman 6.0.2 remote client can run on a cgroups v1 Linux host, but the Podman 6 engine still cannot.

Apply unified configuration precedence

Do not merge every main file. For each supported config, Podman selects only the highest-priority existing main file: user, then administrator, then vendor. Even an empty user main file suppresses lower-tier main files.

Then apply drop-ins from all applicable tiers:

1. Mask earlier same-named files with files from later locations.
2. Sort the surviving files globally by filename.
3. Let lexicographically later filenames win, regardless of tier; a vendor 99-*.conf can override a user 33-*.conf.

Use CONTAINERS_<NAME>_CONF to select one file and disable normal loading. Use CONTAINERS_<NAME>_CONF_OVERRIDE to load one final override after the normal stack. Restart the Podman service process after configuration changes; in-process reload is gone.

Update configuration and Go consumers

• Stop using /etc/containers/containers.rootless.conf; put root-mode customization in drop-ins.
• Replace storage rootless_storage_path with graphroot in a rootless drop-in.
• Replace registries.conf V1 and REGISTRIES_CONFIG_PATH with V2 and CONTAINERS_REGISTRIES_CONF.
• Cache DefaultStoreOptions() in storage-library code; ReloadConfigurationFile(), UpdateStoreOptions(), and Save() are removed.
• Move Go imports from github.com/containers/podman/v5 to go.podman.io/podman/v6.
• Remove the redundant nameOrID argument from binding calls to artifacts.Remove().

Account for changed defaults and output

• Network isolation is enabled by default.
• podman volume prune removes only unused anonymous volumes; use --all for the former scope and --dry-run to preview. Before 6.1, do not combine --all with a label filter.
• podman commit pauses the container by default; use --pause=false only when inconsistent concurrent changes are acceptable.
• Repeated volume-list filters and repeated supported label!= filters combine with AND.
• An unset inspected MemorySwappiness is nil, not -1.
• {{json .Labels}} in container, pod, and volume list templates produces comma-separated key=value text, not a JSON object.
• Pod start/stop prints the identifier supplied by the caller, not necessarily a full ID.
• SIGTERM no longer implies a successful Podman exit.
• A one-element inspected command appears in Path with an empty Args array.

Security and compatibility floors

Use a patched maintenance release whenever the affected path is present:

High-value command and configuration patterns

Manage Quadlets locally

Use podman quadlet install, list, print, and rm for current-user units. These commands were local-only when introduced. A bundled install file may contain several units; separate sections with --- and start each with # FileName=<name>.

# FileName=app.container
[Container]
Image=docker.io/library/alpine:latest
---
# FileName=data.volume
[Volume]

Expect installed units and auxiliary files in subdirectories rather than a tracked .app file. Use podman quadlet list --format ... for scriptable output; it suppresses headings, can filter by status, and exposes a container unit's pod.

Use current container controls

podman update --ulimit nofile=4096:8192 web
podman update --no-healthcheck web
podman exec --no-session web true
podman wait --return-on-first ctr1 ctr2
podman run --userns=keep-id:size=65536 IMAGE
podman run --mount type=volume,src=myvol,dst=/mnt,nocreate IMAGE

• Update environment with podman update --env and --unsetenv; target the newest container with --latest.
• Use --health-log-destination, --health-max-log-count, and --health-max-log-size to bound health logs.
• Expect timed-out health checks to receive SIGTERM and then SIGKILL after a delay.
• Use --gpus for AMD GPUs as well as other supported GPU devices.
• Use --log-opt label=... only with the journald log driver.

Use current volume, network, and Kubernetes features

podman volume prune --dry-run
podman run --net mynet:ip=10.0.0.2,ip=10.0.0.3 IMAGE
podman network create --route 10.20.30.0/24,blackhole isolated
podman kube play app.yaml worker.yaml

• Use subpath= to mount only a volume subdirectory and nocreate to require an existing named volume.
• Use podman volume create --uid ... --gid ... to set ownership at creation.
• Repeat ip= to assign several addresses on one network; attachment order follows the command line.
• Use --no-pod-prefix cautiously: a pod and container with the same resulting name conflict.
• Treat untrusted Kubernetes YAML as hostile and enforce the security floor above.

Use stable OCI artifacts

Manage artifacts with podman artifact add, inspect, ls, pull, push, and rm. Mount them with type=artifact; use name= to choose the exposed filename. A single-blob artifact mounts as a file when the destination does not already exist in the image.

podman run --mount type=artifact,src=example.com/acme/data:latest,dst=/data,name=payload IMAGE

Use .artifact Quadlet units for systemd-managed artifacts. For service-local content, use the local artifact API; for remote uploads, use the tar-body endpoint in the API reference.

Work across machine providers

Treat the configured machine provider as the default for new VMs only. Every machine command can address VMs from every provider. Select a provider at creation and suppress default-connection prompts explicitly in automation:

podman machine init --provider libkrun --update-connection=false dev

Recreate existing Linux machine VMs after adopting Podman 6 because systemd-based host volume mounting is incompatible with their old mounts. Use --import-native-ca when the VM must trust host CAs, and remember that machine os update is unavailable with WSL.

Verification checklist

• Inspect the relevant topic reference before editing commands or parsing output.
• Confirm the installed maintenance release before relying on a security or compatibility fix.
• Preview destructive storage work with --dry-run where supported and stop background services before database migration.
• Restart the system service after configuration changes.
• Test remote and local clients separately when a feature has transport-specific coverage.
• Recheck scripts that parse IDs, labels, statuses, image fields, or Compat API responses.