podman-image-scp(1)

💅 podman-image-scp — bestie's field guide to yeeting images across the network

okay so this is page podman-image-scp(1) from the General Commands Manual, and honestly? it's lowkey iconic. grab a snack, we're moving container images between hosts 🦋

---

✨ NAME ✨

podman-image-scp — securely copy an image from one host to another. that's it, that's the whole vibe 🎀

---

🌸 SYNOPSIS 🌸

podman image scp [options] name[:tag]

---

💜 DESCRIPTION 💜

okay so podman image scp copies container images between hosts on a network. yes bestie, it's giving "filesystem courier but make it containers" ✨. it can copy images to the remote host, from the remote host, and even between two remote hosts — the range, the versatility, we love to see it 👑

📌 note: :: is used to specify the image name depending on Podman is saving or loading. iykyk — those two little colons are doing so much work fr fr.

images can also be transferred from rootful to rootless storage on the same machine without using sshd. no daemon, no drama, no cap 💅. but heads up: this feature is not supported on the remote client, including Mac and Windows (excluding WSL2) machines. so if you're on Mac or Windows and not in WSL2... bestie, this one's not for you 😭.

now the important part, and i need you to actually read this one 🫶: this is not a direct storage-to-storage copy. the image gets saved to an archive (using podman save), the archive file gets transferred (e.g., over SSH), and then it's loaded on the destination. it's giving relay race, not teleportation 🏃‍♀️.

and because of that whole archive detour: digest references to the original compressed blobs are not preserved (e.g., podman pull image@digest followed by podman image scp and then inspecting by that digest may not work). like, the digest is not coming to the afterparty 😔. for regular workflows, using a registry (push from source, pull on destination) is often preferable — genuinely the more chill option ngl.

here's all the ways you can call it, in their exact little lineup:

podman image scp [GLOBAL OPTIONS]

podman image scp [OPTIONS] NAME[:TAG] [HOSTNAME::]

podman image scp [OPTIONS] [HOSTNAME::]IMAGENAME

podman image scp [OPTIONS] [HOSTNAME::]IMAGENAME [HOSTNAME::]

look at those four forms, main character energy each and every one 🌈

---

🔥 OPTIONS 🔥

• --format=format — the format passed to podman save when creating the transfer archive. allowed values are oci-archive and docker-archive. if you omit it, podman save uses its default (docker-archive). only the oci-archive and docker-archive archive (tar) formats are supported — directory formats (oci-dir, docker-dir) are not supported, because the transfer sends a single file and the remote path does not support directory layouts. so no, you can't sneak a dir format in there, she said what she said 💅
• --help, -h — print usage statement. the classic "help me help you" 🫶
• --quiet, -q — suppress the output. for when you want the copy and not the commentary 🤫

---

🎀 EXAMPLES 🎀

copy specified image to local storage:

$ podman image scp alpine
Loaded image: docker.io/library/alpine:latest

copy specified image from local storage to remote connection:

$ podman image scp alpine Fedora::/home/charliedoern/Documents/alpine
Getting image source signatures
Copying blob 72e830a4dff5 done
Copying config 85f9dc67c7 done
Writing manifest to image destination
Storing signatures
Loaded image: docker.io/library/alpine:latest

copy specified image from remote connection to remote connection:

$ podman image scp Fedora::alpine RHEL::
Loaded image: docker.io/library/alpine:latest

copy specified image via ssh to local storage:

$ podman image scp charliedoern@192.168.68.126:22/run/user/1000/podman/podman.sock::alpine
WARN[0000] Unknown connection name given. Please use system connection add to specify the default remote socket location
Getting image source signatures
Copying blob 9450ef9feb15 [--------------------------------------] 0.0b / 0.0b
Copying config 1f97f0559c done
Writing manifest to image destination
Storing signatures
Loaded image: docker.io/library/alpine:latest

(that WARN is just the tool being honest with you, not mean 💀)

copy specified image from root account to user accounts local storage:

$ sudo podman image scp root@localhost::alpine username@localhost::
Copying blob e2eb06d8af82 done
Copying config 696d33ca15 done
Writing manifest to image destination
Storing signatures
Getting image source signatures
Copying blob 5eb901baf107 skipped: already exists
Copying config 696d33ca15 done
Writing manifest to image destination
Storing signatures
Loaded image: docker.io/library/alpine:latest

see that skipped: already exists? efficiency, we stan 🧚

copy specified image from root account to local storage:

$ sudo podman image scp root@localhost::alpine
Copying blob e2eb06d8af82 done
Copying config 696d33ca15 done
Writing manifest to image destination
Storing signatures
Getting image source signatures
Copying blob 5eb901baf107
Copying config 696d33ca15 done
Writing manifest to image destination
Storing signatures
Loaded image: docker.io/library/alpine:latest

copy image to rootful storage with OCI archive format:

$ podman image scp --format oci-archive quay.io/fedora/fedora:43 root@localhost::

copy image to remote host (uses default format when --format is omitted):

$ podman image scp alpine root@myserver::

---

👑 SEE ALSO 👑

podman(1), podman-load(1), podman-save(1), podman-remote(1), podman-system-connection-add(1), containers.conf(5), containers-transports(5)

go read the friends, they're all part of the squad 💖

---

⭐ HISTORY ⭐

July 2021, Originally written by Charlie Doern cdoern@redhat.com ⟨mailto:cdoern@redhat.com⟩

shoutout to the original author, absolute legend 🌟

---

and that's the page bestie!! 🫶 this was podman-image-scp(1) — originally written July 2021, and it's still out here securely copying images like the icon it is. now go forth and scp responsibly 💅✨🍓