Skopeo: The Container Image Swiss Army Knife You Didn't Know You Needed

Apr 15, 2025 · 8 min read · kubernetes skopeo images gpg

Overview

Ever found yourself needing to peek inside a container image without the hassle of pulling it? Or perhaps you wished for a smoother way to transfer images between registries without the Docker daemon breathing down your neck? Enter Skopeo — the command-line tool that lets you inspect, copy, and even sign container images, all without the need for a local container runtime.

Installing Skopeo

macOS (via Homebrew)

1brew install skopeo

Ubuntu

1sudo apt install skopeo

For other distributions and detailed instructions, refer to the official installation guide.

Inspecting Images Without Pulling

Curious about what’s inside an image but don’t want to download it? Skopeo’s inspect command has you covered:

1skopeo inspect docker://docker.io/library/nginx:latest

This command fetches metadata like layers, digests, and labels directly from the registry, saving you time and bandwidth. It’s like having X-ray vision for container images!

When using skopeo inspect on macOS, you might encounter the following error:

1FATA[0001] Error parsing manifest for image: choosing image instance: no image found in image index for architecture "arm64", variant "v8", OS "darwin"

This occurs because the image you’re inspecting is a multi-architecture (multi-arch) image, and it doesn’t include a variant compatible with your system’s architecture and operating system. Skopeo attempts to select the appropriate image variant based on your current platform, and if it doesn’t find a match, it throws this error.

1skopeo inspect \
2  --override-arch amd64 \
3  --override-os linux \
4  docker://docker.io/library/nginx:latest

This command tells Skopeo to inspect the amd64 architecture variant for the linux operating system, bypassing the default behavior of matching your current platform.

 1{
 2    "Name": "docker.io/library/nginx",
 3    "Digest": "sha256:09369da6b10306312cd908661320086bf87fbae1b6b0c49a1f50ba531fef2eab",
 4    "RepoTags": [
 5        "1",
 6        "1-alpine",
 7        "1-alpine-otel",
 8        "1-alpine-perl",
 9        "1-alpine-slim",
10        "1-alpine3.17",
11        "1-alpine3.17-perl",
12        "1-alpine3.17-slim",
13        ...
14        "stable-bookworm",
15        "stable-bookworm-otel",
16        "stable-bookworm-perl",
17        "stable-bullseye",
18        "stable-bullseye-perl",
19        "stable-otel",
20        "stable-perl"
21    ],
22    "Created": "2025-02-05T21:27:16Z",
23    "DockerVersion": "",
24    "Labels": {
25        "maintainer": "NGINX Docker Maintainers \[email protected]\u003e"
26    },
27    "Architecture": "amd64",
28    "Os": "linux",
29    "Layers": [
30        "sha256:8a628cdd7ccc83e90e5a95888fcb0ec24b991141176c515ad101f12d6433eb96",
31        "sha256:75b6425929919354127c44985ea613fa508df8d80dbd1beafeb629400efb7541",
32        "sha256:553c8756fd6670dc339ab500b042fe404386f114673f9c8af8dff3c6ade96cc7",
33        "sha256:10fe6d2248e3ac5eab320a5c240e1aabfb0249d7b4b438b136633a8cbdc2190f",
34        "sha256:3b6e18ae4ce61fa7b74c27a0b077d76bd53699d7e55b9e6a438c62282c0153e7",
35        "sha256:3dce86e3b08256a60ab97ef86944f0c2a1e5c90a2df7806043c9969decfd82e8",
36        "sha256:e81a6b82cf648bedba69393d4a1c09839203d02587537c8c9a7703c01b37af49"
37    ],
38    "LayersData": [
39        {
40            "MIMEType": "application/vnd.oci.image.layer.v1.tar+gzip",
41            "Digest": "sha256:8a628cdd7ccc83e90e5a95888fcb0ec24b991141176c515ad101f12d6433eb96",
42            "Size": 28227259,
43            "Annotations": null
44        },
45        {
46            "MIMEType": "application/vnd.oci.image.layer.v1.tar+gzip",
47            "Digest": "sha256:75b6425929919354127c44985ea613fa508df8d80dbd1beafeb629400efb7541",
48            "Size": 43954583,
49            "Annotations": null
50        },
51        {
52            "MIMEType": "application/vnd.oci.image.layer.v1.tar+gzip",
53            "Digest": "sha256:553c8756fd6670dc339ab500b042fe404386f114673f9c8af8dff3c6ade96cc7",
54            "Size": 626,
55            "Annotations": null
56        },
57        {
58            "MIMEType": "application/vnd.oci.image.layer.v1.tar+gzip",
59            "Digest": "sha256:10fe6d2248e3ac5eab320a5c240e1aabfb0249d7b4b438b136633a8cbdc2190f",
60            "Size": 952,
61            "Annotations": null
62        },
63        {
64            "MIMEType": "application/vnd.oci.image.layer.v1.tar+gzip",
65            "Digest": "sha256:3b6e18ae4ce61fa7b74c27a0b077d76bd53699d7e55b9e6a438c62282c0153e7",
66            "Size": 399,
67            "Annotations": null
68        },
69        {
70            "MIMEType": "application/vnd.oci.image.layer.v1.tar+gzip",
71            "Digest": "sha256:3dce86e3b08256a60ab97ef86944f0c2a1e5c90a2df7806043c9969decfd82e8",
72            "Size": 1210,
73            "Annotations": null
74        },
75        {
76            "MIMEType": "application/vnd.oci.image.layer.v1.tar+gzip",
77            "Digest": "sha256:e81a6b82cf648bedba69393d4a1c09839203d02587537c8c9a7703c01b37af49",
78            "Size": 1400,
79            "Annotations": null
80        }
81    ],
82    "Env": [
83        "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
84        "NGINX_VERSION=1.27.4",
85        "NJS_VERSION=0.8.9",
86        "NJS_RELEASE=1~bookworm",
87        "PKG_RELEASE=1~bookworm",
88        "DYNPKG_RELEASE=1~bookworm"
89    ]
90}

Alternatively, if you want to view all available architecture variants for a multi-arch image, you can use the --raw flag to output the raw manifest:

1skopeo inspect \
2  --raw docker://docker.io/library/nginx:latest | jq

  1{
  2  "manifests": [
  3    {
  4      "annotations": {
  5        "com.docker.official-images.bashbrew.arch": "amd64",
  6        "org.opencontainers.image.base.digest": "sha256:4b44499bc2a6c78d726f3b281e6798009c0ae1f034b0bfaf6a227147dcff928b",
  7        "org.opencontainers.image.base.name": "debian:bookworm-slim",
  8        "org.opencontainers.image.created": "2025-04-08T01:45:51Z",
  9        "org.opencontainers.image.revision": "cffeb933620093bc0c08c0b28c3d5cbaec79d729",
 10        "org.opencontainers.image.source": "https://github.com/nginxinc/docker-nginx.git#cffeb933620093bc0c08c0b28c3d5cbaec79d729:mainline/debian",
 11        "org.opencontainers.image.url": "https://hub.docker.com/_/nginx",
 12        "org.opencontainers.image.version": "1.27.4"
 13      },
 14      "digest": "sha256:b6653fca400812e81569f9be762ae315db685bc30b12ddcdc8616c63a227d3ca",
 15      "mediaType": "application/vnd.oci.image.manifest.v1+json",
 16      "platform": {
 17        "architecture": "amd64",
 18        "os": "linux"
 19      },
 20      "size": 2295
 21    },
 22    {
 23      "annotations": {
 24        "com.docker.official-images.bashbrew.arch": "amd64",
 25        "vnd.docker.reference.digest": "sha256:b6653fca400812e81569f9be762ae315db685bc30b12ddcdc8616c63a227d3ca",
 26        "vnd.docker.reference.type": "attestation-manifest"
 27      },
 28      "digest": "sha256:1fe8bc57e04d3add4c87bbc14f91569f392481a994ea47fc03b030a962a8a851",
 29      "mediaType": "application/vnd.oci.image.manifest.v1+json",
 30      "platform": {
 31        "architecture": "unknown",
 32        "os": "unknown"
 33      },
 34      "size": 841
 35    },
 36    {
 37      "annotations": {
 38        "com.docker.official-images.bashbrew.arch": "arm32v5",
 39        "org.opencontainers.image.base.digest": "sha256:bf7ee0e80bc3f33bb693584818c1125cc4e6f1a2e12abfac2dd5fe3a0e0b9e73",
 40        "org.opencontainers.image.base.name": "debian:bookworm-slim",
 41        "org.opencontainers.image.created": "2025-04-08T01:52:17Z",
 42        "org.opencontainers.image.revision": "cffeb933620093bc0c08c0b28c3d5cbaec79d729",
 43        "org.opencontainers.image.source": "https://github.com/nginxinc/docker-nginx.git#cffeb933620093bc0c08c0b28c3d5cbaec79d729:mainline/debian",
 44        "org.opencontainers.image.url": "https://hub.docker.com/_/nginx",
 45        "org.opencontainers.image.version": "1.27.4"
 46      },
 47      "digest": "sha256:4bcba87eadc6ebb7b51ece2dadfb5493b1616ed5663cbfc6ac30e67dafabc44e",
 48      "mediaType": "application/vnd.oci.image.manifest.v1+json",
 49      "platform": {
 50        "architecture": "arm",
 51        "os": "linux",
 52        "variant": "v5"
 53      },
 54      "size": 2297
 55    },
 56    {
 57      "annotations": {
 58        "com.docker.official-images.bashbrew.arch": "arm32v5",
 59        "vnd.docker.reference.digest": "sha256:4bcba87eadc6ebb7b51ece2dadfb5493b1616ed5663cbfc6ac30e67dafabc44e",
 60        "vnd.docker.reference.type": "attestation-manifest"
 61      },
 62      "digest": "sha256:e4b798256413dfb7b3b8c88d68d4b26b6c9e89e12c73059c9e01c8ef8645c3a3",
 63      "mediaType": "application/vnd.oci.image.manifest.v1+json",
 64      "platform": {
 65        "architecture": "unknown",
 66        "os": "unknown"
 67      },
 68      "size": 841
 69    },
 70    {
 71      "annotations": {
 72        "com.docker.official-images.bashbrew.arch": "arm32v7",
 73        "org.opencontainers.image.base.digest": "sha256:8ba74c566fcc810a50be428d44244c386d27cb93c055480fca8c3f9acf002d08",
 74        "org.opencontainers.image.base.name": "debian:bookworm-slim",
 75        "org.opencontainers.image.created": "2025-04-08T01:51:32Z",
 76        "org.opencontainers.image.revision": "cffeb933620093bc0c08c0b28c3d5cbaec79d729",
 77        "org.opencontainers.image.source": "https://github.com/nginxinc/docker-nginx.git#cffeb933620093bc0c08c0b28c3d5cbaec79d729:mainline/debian",
 78        "org.opencontainers.image.url": "https://hub.docker.com/_/nginx",
 79        "org.opencontainers.image.version": "1.27.4"
 80      },
 81      "digest": "sha256:c50e8278e3d30be67e18be5cdf97280376dc90faf2b94ff99a214576aa7f6cd5",
 82      "mediaType": "application/vnd.oci.image.manifest.v1+json",
 83      "platform": {
 84        "architecture": "arm",
 85        "os": "linux",
 86        "variant": "v7"
 87      },
 88      "size": 2297
 89    },
 90    {
 91      "annotations": {
 92        "com.docker.official-images.bashbrew.arch": "arm32v7",
 93        "vnd.docker.reference.digest": "sha256:c50e8278e3d30be67e18be5cdf97280376dc90faf2b94ff99a214576aa7f6cd5",
 94        "vnd.docker.reference.type": "attestation-manifest"
 95      },
 96      "digest": "sha256:fa8430d8826ed2d8107cca23a3246e7acc3d2b99369f5e6a66585447c2cf76e9",
 97      "mediaType": "application/vnd.oci.image.manifest.v1+json",
 98      "platform": {
 99        "architecture": "unknown",
100        "os": "unknown"
101      },
102      "size": 841
103    },
104    {
105      "annotations": {
106        "com.docker.official-images.bashbrew.arch": "arm64v8",
107        "org.opencontainers.image.base.digest": "sha256:912d8a461ca5f85380a40de97d7b38dfcc39972de210518de07136126dd0bfa9",
108        "org.opencontainers.image.base.name": "debian:bookworm-slim",
109        "org.opencontainers.image.created": "2025-04-08T02:15:21Z",
110        "org.opencontainers.image.revision": "cffeb933620093bc0c08c0b28c3d5cbaec79d729",
111        "org.opencontainers.image.source": "https://github.com/nginxinc/docker-nginx.git#cffeb933620093bc0c08c0b28c3d5cbaec79d729:mainline/debian",
112        "org.opencontainers.image.url": "https://hub.docker.com/_/nginx",
113        "org.opencontainers.image.version": "1.27.4"
114      },
115      "digest": "sha256:846993cfd1ec2f814d7f3cfdc8df7aa67ecfe6ab233fd990c82d34eea47beb8e",
116      "mediaType": "application/vnd.oci.image.manifest.v1+json",
117      "platform": {
118        "architecture": "arm64",
119        "os": "linux",
120        "variant": "v8"
121      },
122      "size": 2297
123    },
124    {
125      "annotations": {
126        "com.docker.official-images.bashbrew.arch": "arm64v8",
127        "vnd.docker.reference.digest": "sha256:846993cfd1ec2f814d7f3cfdc8df7aa67ecfe6ab233fd990c82d34eea47beb8e",
128        "vnd.docker.reference.type": "attestation-manifest"
129      },
130      "digest": "sha256:41e936c6bb4d3fbcb5e0fd33db5287a78b5f6df40c455b0d9ed7337cd51cf209",
131      "mediaType": "application/vnd.oci.image.manifest.v1+json",
132      "platform": {
133        "architecture": "unknown",
134        "os": "unknown"
135      },
136      "size": 841
137    },
138    {
139      "annotations": {
140        "com.docker.official-images.bashbrew.arch": "i386",
141        "org.opencontainers.image.base.digest": "sha256:546fc136c89a1b0554689e33bfe000687048faddee5157844b374acc03d773fd",
142        "org.opencontainers.image.base.name": "debian:bookworm-slim",
143        "org.opencontainers.image.created": "2025-04-08T01:11:42Z",
144        "org.opencontainers.image.revision": "cffeb933620093bc0c08c0b28c3d5cbaec79d729",
145        "org.opencontainers.image.source": "https://github.com/nginxinc/docker-nginx.git#cffeb933620093bc0c08c0b28c3d5cbaec79d729:mainline/debian",
146        "org.opencontainers.image.url": "https://hub.docker.com/_/nginx",
147        "org.opencontainers.image.version": "1.27.4"
148      },
149      "digest": "sha256:31eefa9ba775ea648b8e5b9bd8ea834f3f0c86dbfb8513d34d6d6ae0645cc178",
150      "mediaType": "application/vnd.oci.image.manifest.v1+json",
151      "platform": {
152        "architecture": "386",
153        "os": "linux"
154      },
155      "size": 2294
156    },
157    {
158      "annotations": {
159        "com.docker.official-images.bashbrew.arch": "i386",
160        "vnd.docker.reference.digest": "sha256:31eefa9ba775ea648b8e5b9bd8ea834f3f0c86dbfb8513d34d6d6ae0645cc178",
161        "vnd.docker.reference.type": "attestation-manifest"
162      },
163      "digest": "sha256:db10be2e0d2af5e97a58bf4317cc1534734f9aaf5c3bf071cf9fb0ec7b7c8a87",
164      "mediaType": "application/vnd.oci.image.manifest.v1+json",
165      "platform": {
166        "architecture": "unknown",
167        "os": "unknown"
168      },
169      "size": 841
170    },
171    {
172      "annotations": {
173        "com.docker.official-images.bashbrew.arch": "mips64le",
174        "org.opencontainers.image.base.digest": "sha256:32127f41084d3360f90315ef0c7c0deb43c73ee02382035c35ce978dad94b35d",
175        "org.opencontainers.image.base.name": "debian:bookworm-slim",
176        "org.opencontainers.image.created": "2025-04-08T02:21:58Z",
177        "org.opencontainers.image.revision": "cffeb933620093bc0c08c0b28c3d5cbaec79d729",
178        "org.opencontainers.image.source": "https://github.com/nginxinc/docker-nginx.git#cffeb933620093bc0c08c0b28c3d5cbaec79d729:mainline/debian",
179        "org.opencontainers.image.url": "https://hub.docker.com/_/nginx",
180        "org.opencontainers.image.version": "1.27.4"
181      },
182      "digest": "sha256:4a2475325e9bfd3afe7072826692a96265d3f8d21998f2053c1cfa4cb10ead7b",
183      "mediaType": "application/vnd.oci.image.manifest.v1+json",
184      "platform": {
185        "architecture": "mips64le",
186        "os": "linux"
187      },
188      "size": 2298
189    },
190    {
191      "annotations": {
192        "com.docker.official-images.bashbrew.arch": "mips64le",
193        "vnd.docker.reference.digest": "sha256:4a2475325e9bfd3afe7072826692a96265d3f8d21998f2053c1cfa4cb10ead7b",
194        "vnd.docker.reference.type": "attestation-manifest"
195      },
196      "digest": "sha256:291f0ff112d6349f8e911e085ec08fd8573fd7cd2efe786dce2e2ec12edaa221",
197      "mediaType": "application/vnd.oci.image.manifest.v1+json",
198      "platform": {
199        "architecture": "unknown",
200        "os": "unknown"
201      },
202      "size": 567
203    },
204    {
205      "annotations": {
206        "com.docker.official-images.bashbrew.arch": "ppc64le",
207        "org.opencontainers.image.base.digest": "sha256:6d08d69167c094bb6f76c99167391ff6c35ee237eb48f2e3ea7fdb65608ce4d2",
208        "org.opencontainers.image.base.name": "debian:bookworm-slim",
209        "org.opencontainers.image.created": "2025-04-08T01:48:12Z",
210        "org.opencontainers.image.revision": "cffeb933620093bc0c08c0b28c3d5cbaec79d729",
211        "org.opencontainers.image.source": "https://github.com/nginxinc/docker-nginx.git#cffeb933620093bc0c08c0b28c3d5cbaec79d729:mainline/debian",
212        "org.opencontainers.image.url": "https://hub.docker.com/_/nginx",
213        "org.opencontainers.image.version": "1.27.4"
214      },
215      "digest": "sha256:fddb0f09b70b961b484c8694006384c04e245b4f8c35f28cc1e93ac89b34869d",
216      "mediaType": "application/vnd.oci.image.manifest.v1+json",
217      "platform": {
218        "architecture": "ppc64le",
219        "os": "linux"
220      },
221      "size": 2297
222    },
223    {
224      "annotations": {
225        "com.docker.official-images.bashbrew.arch": "ppc64le",
226        "vnd.docker.reference.digest": "sha256:fddb0f09b70b961b484c8694006384c04e245b4f8c35f28cc1e93ac89b34869d",
227        "vnd.docker.reference.type": "attestation-manifest"
228      },
229      "digest": "sha256:634af8de5bdf18b1f6ff5614a6cc7a082d2390efa28f99f1dae67cab60713288",
230      "mediaType": "application/vnd.oci.image.manifest.v1+json",
231      "platform": {
232        "architecture": "unknown",
233        "os": "unknown"
234      },
235      "size": 841
236    },
237    {
238      "annotations": {
239        "com.docker.official-images.bashbrew.arch": "s390x",
240        "org.opencontainers.image.base.digest": "sha256:604d86fd7ef6bb1e6dc5709e4149cb81953d5f006aa41f376aef84c7f152f332",
241        "org.opencontainers.image.base.name": "debian:bookworm-slim",
242        "org.opencontainers.image.created": "2025-04-08T01:48:17Z",
243        "org.opencontainers.image.revision": "cffeb933620093bc0c08c0b28c3d5cbaec79d729",
244        "org.opencontainers.image.source": "https://github.com/nginxinc/docker-nginx.git#cffeb933620093bc0c08c0b28c3d5cbaec79d729:mainline/debian",
245        "org.opencontainers.image.url": "https://hub.docker.com/_/nginx",
246        "org.opencontainers.image.version": "1.27.4"
247      },
248      "digest": "sha256:a99b7d9812dbb7527eab8161807e879c3e66951ddccf21c5302061a651289da6",
249      "mediaType": "application/vnd.oci.image.manifest.v1+json",
250      "platform": {
251        "architecture": "s390x",
252        "os": "linux"
253      },
254      "size": 2295
255    },
256    {
257      "annotations": {
258        "com.docker.official-images.bashbrew.arch": "s390x",
259        "vnd.docker.reference.digest": "sha256:a99b7d9812dbb7527eab8161807e879c3e66951ddccf21c5302061a651289da6",
260        "vnd.docker.reference.type": "attestation-manifest"
261      },
262      "digest": "sha256:a1e6f44bc7da1981130e18b36c1429d2a436a068642853d67ba36eaab952a2c6",
263      "mediaType": "application/vnd.oci.image.manifest.v1+json",
264      "platform": {
265        "architecture": "unknown",
266        "os": "unknown"
267      },
268      "size": 841
269    }
270  ],
271  "mediaType": "application/vnd.oci.image.index.v1+json",
272  "schemaVersion": 2
273}

This will display the manifest list, including all supported architectures and operating systems for the image.

By using these options, you can effectively inspect and work with multi-architecture images, even when your current platform isn’t directly supported by the image’s manifest.

Copying Images Between Registries

Transferring images between registries can be a chore, especially when dealing with authentication and different formats. Skopeo simplifies this process:

1skopeo copy \
2  docker://source.registry.com/myimage:latest \
3  docker://destination.registry.com/myimage:latest

Need to handle credentials? No problem:

1skopeo copy \
2  --dest-creds user:password \
3  docker://source.registry.com/myimage:latest \
4  docker://destination.registry.com/myimage:latest

You might need to check other authentication flags depending on your setup.

Signing Images for Enhanced Security

In today’s security-conscious world, signing your container images is a best practice. Skopeo supports image signing using GPG:

Generate a GPG key:

1gpg --generate-key

Follow the steps to generate, or use an existing one gpg -K

Sign the image during copy:

1skopeo copy \
2  --sign-by YOUR_KEY_ID \
3  docker://source.registry.com/myimage:latest \
4  docker://destination.registry.com/myimage:latest

Verify a signed image

1skopeo inspect --verify-signatures docker://destination.registry.com/myimage:latest

 1{
 2  "Name": "destination.registry.com/myimage",
 3  "Digest": "sha256:...",
 4  "RepoTags": [
 5    "tag"
 6  ],
 7  "Created": "2025-04-15T12:34:56Z",
 8  "DockerVersion": "20.10.7",
 9  "Labels": {
10    "maintainer": "[email protected]"
11  },
12  "Architecture": "amd64",
13  "Os": "linux",
14  "Layers": [
15    "sha256:..."
16  ]
17}

If the verification fails, you would receive the following message:

1FATA[0001] Signature for docker://destination.registry.com/myimage:latest is not valid: signature verification failed: no valid signatures found

That’s about it! Skopeo is a powerful and flexible tool that can seriously level up your container workflows. Whether you’re automating image promotion across environments, verifying signatures for security, or just avoiding the hassle of pulling and pushing images manually — Skopeo has your back. It plays well in CI pipelines, helps keep registries clean and in sync, and makes inspecting remote images a breeze. Give it a spin, and you might wonder how you ever managed without it.