CONTAINERS-TRANSPORTS(5) Man CONTAINERS-TRANSPORTS(5)
Valentin Rothberg April 2019
NAME
containers-transports - description of supported transports for copying
and storing container images
DESCRIPTION
Tools which use the containers/image library, including skopeo(1), buil-
dah(1), podman(1), all share a common syntax for referring to container
images in various locations. The general form of the syntax is trans-
port:details, where details are dependent on the specified transport,
which are documented below.
The semantics of the image names ultimately depend on the environment
where they are evaluated. For example: if evaluated on a remote server,
image names might refer to paths on that server; relative paths are rel-
ative to the current directory of the image consumer.
containers-storage:[[storage-specifier]]{image-id|docker-reference[@image-
id]}
An image located in a local containers storage. The format of docker-
reference is described in detail in the docker transport.
The storage-specifier allows for referencing storage locations on the
file system and has the format [[driver@]root[+run-root][:options]]
where the optional driver refers to the storage driver (e.g., overlay or
btrfs) and where root is an absolute path to the storage's root direc-
tory. The optional run-root can be used to specify the run directory of
the storage where all temporary writable content is stored. The op-
tional options are a comma-separated list of driver-specific options.
Please refer to containers-storage.conf(5) for further information on
the drivers and supported options.
dir:path
An existing local directory path storing the manifest, layer tarballs
and signatures as individual files. This is a non-standardized format,
primarily useful for debugging or noninvasive container inspection.
docker://docker-reference
An image in a registry implementing the "Docker Registry HTTP API V2".
By default, uses the authorization state in $XDG_RUNTIME_DIR/contain-
ers/auth.json, which is set using podman-login(1). If the authorization
state is not found there, $HOME/.docker/config.json is checked, which is
set using docker-login(1). The containers-registries.conf(5) further
allows for configuring various settings of a registry.
Note that a docker-reference has the following format: name[:tag | @di-
gest]. While the docker transport does not support both a tag and a di-
gest at the same time some formats like containers-storage do. Digests
can also be used in an image destination as long as the manifest matches
the provided digest.
The docker transport supports pushing images without a tag or digest to
a registry when the image name is suffixed with @@unknown-digest@@. The
name@@unknown-digest@@ reference format cannot be used with a reference
that has a tag or digest. The digest of images can be explored with
skopeo-inspect(1).
If name does not contain a slash, it is treated as docker.io/li-
brary/name. Otherwise, the component before the first slash is checked
if it is recognized as a hostname ⟨i.e., it contains either a `.` or a
`:`, or the component is exactly `localhost`⟩. If the first component
of name is not recognized as a hostname[:port], name is treated as
docker.io/name.
docker-archive:path[:{docker-reference|@source-index}]
An image is stored in the docker-save(1) formatted file.
Unless a tool explicitly documents otherwise, a write to a docker-
archive: destination completely overwrites path, replacing it with the
single provided image.
The path can refer to a stream, e.g. docker-archive:/dev/stdin.
docker-reference must not contain a digest. Alternatively, for reading
archives, @source-index is a zero-based index in archive manifest (to
access untagged images). If neither docker-reference nor @_source_index
is specified when reading an archive, the archive must contain exactly
one image.
docker-daemon:docker-reference|algo:digest
An image stored in the docker daemon's internal storage. The image must
be specified as a docker-reference or in an alternative algo:digest for-
mat when being used as an image source. The algo:digest refers to the
image ID reported by docker-inspect(1).
oci:path[:{reference|@source-index}]
An image in a directory structure compliant with the "Open Container Im-
age Layout Specification" at path.
The path value terminates at the first : character; any further : char-
acters are not separators, but a part of reference. The reference is
used to set, or match, the org.opencontainers.image.ref.name annotation
in the top-level index. If reference is not specified when reading an
image, the directory must contain exactly one image. For reading im-
ages, @source-index is a zero-based index in manifest (to access un-
tagged images). If neither reference nor @_source_index is specified
when reading an image, the path must contain exactly one image.
oci-archive:path[:reference]
An image in a tar(1) archive with contents compliant with the "Open Con-
tainer Image Layout Specification" at path.
Unless a tool explicitly documents otherwise, a write to an oci-archive:
destination completely overwrites path, replacing it with the single
provided image.
The path value terminates at the first : character; any further : char-
acters are not separators, but a part of reference. The reference is
used to set, or match, the org.opencontainers.image.ref.name annotation
in the top-level index. If reference is not specified when reading an
archive, the archive must contain exactly one image.
ostree:docker-reference[@/absolute/repo/path]
An image in the local ostree(1) repository. /absolute/repo/path de-
faults to /ostree/repo.
sif:path
An image using the Singularity image format at path.
Only reading images is supported, and not all scripts can be represented
in the OCI format.
Examples
The following examples demonstrate how some of the containers transports
can be used. The examples use skopeo-copy(1) for copying container im-
ages.
Copying an image from one registry to another:
$ skopeo copy docker://docker.io/library/alpine:latest docker://localhost:5000/alpine:latest
Copying an image from a running Docker daemon to a directory in the OCI
layout:
$ mkdir alpine-oci
$ skopeo copy docker-daemon:alpine:latest oci:alpine-oci
$ tree alpine-oci
test-oci/
├── blobs
│ └── sha256
│ ├── 83ef92b73cf4595aa7fe214ec6747228283d585f373d8f6bc08d66bebab531b7
│ ├── 9a6259e911dcd0a53535a25a9760ad8f2eded3528e0ad5604c4488624795cecc
│ └── ff8df268d29ccbe81cdf0a173076dcfbbea4bb2b6df1dd26766a73cb7b4ae6f7
├── index.json
└── oci-layout
2 directories, 5 files
Copying an image from a registry to the local storage:
$ skopeo copy docker://docker.io/library/alpine:latest containers-storage:alpine:latest
SEE ALSO
docker-login(1), docker-save(1), ostree(1), podman-login(1), skopeo-
copy(1), skopeo-inspect(1), tar(1), container-registries.conf(5), con-
tainers-storage.conf(5)
AUTHORS
Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩ Valentin Roth-
berg rothberg@redhat.com ⟨mailto:rothberg@redhat.com⟩
Transports Containers CONTAINERS-TRANSPORTS(5)
Generated by dwww version 1.16 on Tue Dec 16 06:56:28 CET 2025.