12 Skopeo

Use Skopeo to inspect and copy Open Container Initiative compliant images between container storage types.

Skopeo is an optional utility that you can install in addition to Podman to inspect images in remote registries, and copy images between different types of Open Container Initiative compatible container storage. Skopeo doesn't require a running daemon to function.

Note:

You don't need root permissions to run Skopeo commands. If any errors are returned, ensure that you have configured the appropriate proxy server settings, and that you have the necessary access permissions for the remote registries that you're using.

For more information, see the skopeo(1) manual page.

Inspecting an Image

Use the skopeo inspect command to inspect information about an image in a container registry.

The skopeo inspect command prints information about a container, such as when it was created, its SHA digest signature, and the environment variables that are set for the image. The information can also be useful for inspecting the available tags for an image name in a registry.

For more information about the skopeo inspect command, see the skopeo-inspect(1) manual page.

Example 12-1 Inspect an image in a container registry

skopeo inspect docker://container-registry.oracle.com/os/oraclelinux:9

The output looks similar to:

{
    "Name": "container-registry.oracle.com/os/oraclelinux",
    "Digest": "sha256:afeedad1979892ba77973ea9900dc2604873651b0ee8868bffff8c7987e32bb3",
    "RepoTags": [
        "10-slim",
        "10",
        "5.11",
        "5",
        "6-slim",
        "6.10",
        "6.6",
        "6.7",
        "6.8",
        "6.9",
        "6",
        "7-slim-amd64",
        "7-slim-arm64v8",
        "7-slim-fips-amd64",
        "7-slim-fips-arm64v8",
        "7-slim-fips",
        "7-slim",
        "7.0",
        "7.1",
        "7.2",
        "7.3",
        "7.4",
        "7.5",
        "7.6",
        "7.7",
        "7.8",
        "7.9",
        "7",
        "8-arm64v8",
        "8-slim-arm64v8",
        "8-slim-fips-amd64",
        "8-slim-fips-arm64v8",
        "8-slim-fips",
        "8-slim",
        "8.0",
        "8.1",
        "8.10-slim-fips",
        "8.10-slim",
        "8.10",
        "8.2",
        "8.3",
        "8.4",
        "8.5",
        "8.6",
        "8.7",
        "8.8",
        "8.9-slim-fips",
        "8.9-slim",
        "8.9",
        "8",
        "9-slim-fips",
        "9-slim",
        "9",
        "9test",
        "latest"
    ],
    "Created": "2025-08-01T17:33:19.437546569Z",
    "DockerVersion": "",
    "Labels": {
        "io.buildah.version": "1.33.11"
    },
    "Architecture": "amd64",
    "Os": "linux",
    "Layers": [
        "sha256:25ef70384958aefe7777e15722705fbaccd630a1aabe14030e2ad22b3c205c37"
    ],
    "LayersData": [
        {
            "MIMEType": "application/vnd.docker.image.rootfs.diff.tar.gzip",
            "Digest": "sha256:25ef70384958aefe7777e15722705fbaccd630a1aabe14030e2ad22b3c205c37",
            "Size": 99740095,
            "Annotations": null
        }
    ],
    "Env": [
        "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
    ]
}

Example 12-2 Inspect the default configuration for an image in a container registry

Review the default configuration settings and build history of an image by including the --config option. 

skopeo inspect --config docker://container-registry.oracle.com/os/oraclelinux:9

The output looks similar to:

{
    "created": "2025-08-01T17:33:19.437546569Z",
    "architecture": "amd64",
    "os": "linux",
    "config": {
        "Env": [
            "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
        ],
        "Cmd": [
            "/bin/bash"
        ],
        "Labels": {
            "io.buildah.version": "1.33.11"
        }
    },
    "rootfs": {
        "type": "layers",
        "diff_ids": [
            "sha256:0ae592ddaa5b488f567f350e0367e2b3f91ea04a23ea8931017916ecc0f922e4"
        ]
    },
    "history": [
        {
            "created": "2025-08-01T17:33:17.828674963Z",
            "created_by": "/bin/sh -c #(nop) ADD file:9d2d55843e86c79ec0db8291fe7f516630a7f7fe2f0a90f2af552882cd94c7e9 in / "
        },
        {
            "created": "2025-08-01T17:33:19.437694874Z",
            "created_by": "/bin/sh -c #(nop) CMD [\"/bin/bash\"]",
            "comment": "FROM c50fc3f29ef2",
            "empty_layer": true
        }
    ]
}

Example 12-3 Inspect an image in an insecure private registry

skopeo inspect --tls-verify=false docker://localhost:5000/myimage:v1

Copying an Image

Use the skopeo copy command to copy container images between container storage types, such as local storage and container registries.

Use the skopeo copy command to copy an image between registries without needing to download it locally first. You can also copy an image to local Podman container storage.

For more information about the skopeo copy command, see the skopeo-copy(1) manual page.

Example 12-4 Copy an image from one registry to another

skopeo copy docker://container-registry.oracle.com/os/oraclelinux:9-slim docker://myregistry.example.com:5000/oraclelinux:9-slim

Example 12-5 Copy an image from a registry to a private insecure registry

To copy an image to a private insecure registry, include the --dest-tls-verify=false option. 

skopeo copy docker://container-registry.oracle.com/os/oraclelinux:9-slim --dest-tls-verify=false docker://localhost:5000/ol9image:v1

Example 12-6 Copy an image from private secure registry to another registry

To copy an image from a private insecure registry, include the --src-tls-verify=false option. 

skopeo copy --src-tls-verify=false docker://localhost:5000/ol9image:v2 docker://myregistry.example.com:5000/oraclelinux:v2

Example 12-7 Copy an image from a registry to the local storage

To copy an image to the local storage, use the containers-storage: prefix for the destination image. 

skopeo copy docker://container-registry.oracle.com/os/oraclelinux:9-slim containers-storage:oraclelinux:9-slim

Example 12-8 Copy an image from local storage to an insecure private registry

To copy an image from the local storage, use the containers-storage: prefix for the source image. 

skopeo copy containers-storage:localhost/oraclelinux:9-slim --dest-tls-verify=false docker://localhost:5000/ol9image:v2

Example 12-9 Copy an image to the local storage extract it

To download an image and review its internal content offline, specify a directory with the dir: prefix. For example, to extract the oraclelinux:9-slim image to the oraclelinux folder in a home directory: 

skopeo copy docker://container-registry.oracle.com/os/oraclelinux:9-slim dir:/home/$USER/oraclelinux

The oraclelinux folder contains a manifest.json file and several tarballs representing the copied image.

Synchronizing Images

Use the skopeo sync command to synchronize images between storage locations. This can be useful to create and keep container mirrors synchronized in an air gapped environment.

You can copy images from one image storage location to another to synchronize images using the skopeo sync command. The images are copied from the source to the destination using a specified transport. The transport must be specified in the command using one of the following transport types:

  • docker: A container registry. This can be used for either the source or destination. If no image tag is specified, all the tags found for the image are copied.

  • dir: A local directory path. This can be used for either the source or destination. When used with the destination, a directory is created for each image that's copied.

  • yaml: A YAML file that contains the list of images to be copied from one container registry to another. This can't be used with the dir transport for local file systems.

The --scoped options adds the name of the source as a prefix to images so that many images with the same name can be stored at the destination image storage type (registry or directory).

Include the --dry-run option with the skopeo sync command to perform a dry run.

The format for a YAML file to use when synchronizing registry images lists the images to copy from one or more registries. For example:

myregistry.example.com:
  images:
    oraclelinux:
      - "9"
      - "10"
localhost:5000:
  images:
    myimage: []
  tls-verify: false

For more information on the skopeo sync command and the options that can be included in the YAML file, see the skopeo-sync(1) manual page.

Example 12-10 Synchronize an image from an insecure registry to local disk

Copy all the images named oraclelinux from a local insecure registry to a local directory. 

skopeo sync --src docker --dest dir --scoped --src-tls-verify=false localhost:5000/oraclelinux $HOME/images/

Example 12-11 Synchronize images from the local disk to a container registry

Copy all the images in a local directory to a registry:

skopeo sync --src dir --dest docker --scoped $HOME/images/localhost:5000 myregistry.example.com:5000/

Example 12-12 Synchronize images in a registry to an insecure private registry

Copy all the images named oraclelinux in a registry to a local private registry. The --append-suffix option adds a suffix to the destination image tag. 

skopeo sync --src docker --dest docker --dest-tls-verify=false --append-suffix '-mirror' myregistry.example.com:5000/oraclelinux localhost:5000/mirror/

Example 12-13 Synchronize images using a YAML file

Copy the images listed in a YAML file named mysync.yaml to an insecure private registry. 

skopeo sync --src yaml --dest docker --dest-tls-verify=false mysync.yaml localhost:5000/mirror/

Deleting an Image

Use the skopeo delete command to delete an image from a container registry or from local container storage.

The skopeo delete command might not work with every container registry, and many registries don't allow this in the default configuration, or at all.

For more information about the skopeo delete command, see the skopeo-delete(1) manual page.

Example 12-14 Delete an image from local storage

skopeo delete containers-storage:oraclelinux:9-slim

Example 12-15 Delete an image from a private registry

skopeo delete docker://myregistry.example.com/oraclelinux:9

Example 12-16 Delete an image from a private insecure registry

skopeo delete --tls-verify=false docker://localhost:5000/myimage:v1