docs: explain save/load vs export/import

The four man pages cross-reference each other but never say how the two
workflows actually differ, which keeps confusing users. save/load work on
images and keep layers, history and tags; export/import work on a
container's filesystem, flattened into a single-layer tarball with no
history (import then builds a new image from it).

Add a short, matching note to each of the four pages pointing at the
complementary command. Kept to that distinction, nothing about pulling
from a registry.

Fixes: #22155

Signed-off-by: Grzegorz Szczepanczyk <g.szczepanczyk@getprintbox.com>
This commit is contained in:
Grzegorz Szczepanczyk 2026-06-19 13:25:06 +02:00
parent df12c9806c
commit 9cb516acb0
4 changed files with 9 additions and 0 deletions

View file

@ -16,6 +16,8 @@ The image of the container exported by **podman export** can be imported by **po
To export image(s) with parent layers, use **podman save**.
Note: `:` is a restricted character and cannot be part of the file name.
**podman export** operates on a *container's* filesystem: it flattens the filesystem into a single-layer tarball with no image layers, history or tags. This is different from **podman save**, which archives an *image* and preserves its layers, history and tags. To archive an image instead, see **podman-save(1)**.
**podman [GLOBAL OPTIONS]**
**podman export [GLOBAL OPTIONS]**

View file

@ -15,6 +15,9 @@ Various image instructions can be configured with the **--change** flag and
a commit message can be set using the **--message** flag.
**reference**, if present, is a tag to assign to the image.
**podman import** is used for importing from the archive generated by **podman export**, that includes the container's filesystem. To import the archive of image layers created by **podman save**, use **podman load**.
**podman import** builds a *new* image from a root-filesystem tarball (such as one produced by **podman export**), as a single layer with no prior image history. This is different from **podman load**, which restores an *image* archived by **podman save**, preserving its layers, history and tags. To load an image archive instead, see **podman-load(1)**.
Note: `:` is a restricted character and cannot be part of the file name.
## OPTIONS

View file

@ -12,6 +12,8 @@ podman\-load - Load image(s) from a tar archive into container storage
**podman load** loads an image from either an **oci-archive** or a **docker-archive** stored on the local machine into container storage. **podman load** reads from stdin by default or a file if the **input** option is set.
**podman load** is used for loading from the archive generated by **podman save**, that includes the image parent layers. To load the archive of container's filesystem created by **podman export**, use **podman import**.
**podman load** operates on *images*: it restores an archive created by **podman save** as the same image, preserving its layers, history and tags. This is different from **podman import**, which builds a *new* image from a root-filesystem tarball (such as one produced by **podman export**) with no image history. To import a container's filesystem instead, see **podman-import(1)**.
The local client further supports loading an **oci-dir** or a **docker-dir** as created with **podman save** (1).
The **quiet** option suppresses the progress output when set.

View file

@ -16,6 +16,8 @@ file using the **output** flag. The **quiet** flag suppresses the output when se
To export the containers, use the **podman export**.
Note: `:` is a restricted character and cannot be part of the file name.
**podman save** operates on *images*: the resulting archive (OCI or docker-archive) preserves the image's layers, history and tags, and is restored as the same image with **podman load**. This is different from **podman export**, which flattens a *container's* filesystem into a single-layer tarball with no image history. To capture a container's filesystem instead, see **podman-export(1)**.
## OPTIONS
@@option dir-compress