---
name: "containers-transports"
section: "5"
platform: "linux"
package: "containers-common"
version: "1:0.69.2-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/containers-transports"
---

# containers-transports(5)

description of supported transports for copying and storing container images

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)](/skopeo/1.md), [buildah(1)](/buildah/1.md), [podman(1)](/podman/1.md), all share a common syntax for referring to container images in various locations. The general form of the syntax is *transport***:***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 relative 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 directory. The optional *run-root* can be used to specify the run directory of the storage where all temporary writable content is stored. The optional *options* are a comma-separated list of driver-specific options. Please refer to [containers-storage.conf(5)](/containers-storage.conf/5.md) 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/containers/auth.json**, which is set using [podman-login(1)](/podman-login/1.md). If the authorization state is not found there, **$HOME/.docker/config.json** is checked, which is set using [docker-login(1)](/docker-login/1.md). The [containers-registries.conf(5)](/containers-registries.conf/5.md) further allows for configuring various settings of a registry.

Note that a *docker-reference* has the following format: *name*\[**:***tag* \| **@***digest*\]. While the docker transport does not support both a tag and a digest 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)](/skopeo-inspect/1.md).

If *name* does not contain a slash, it is treated as **docker.io/library/***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)](/docker-save/1.md) 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* format when being used as an image source. The *algo***:***digest* refers to the image ID reported by [docker-inspect(1)](/docker-inspect/1.md).

### oci:*path*\[:{*reference*\|@*source-index*}\]

An image in a directory structure compliant with the "Open Container Image Layout Specification" at *path*.

The *path* value terminates at the first **:** character; any further **:** characters 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. For reading images, @*source-index* is a zero-based index in manifest (to access untagged 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)](/tar/1.md) archive with contents compliant with the "Open Container 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 **:** characters 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.

### 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)](/skopeo-copy/1.md) for copying container images.

**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-login/1.md), [docker-save(1)](/docker-save/1.md), [podman-login(1)](/podman-login/1.md), [skopeo-copy(1)](/skopeo-copy/1.md), [skopeo-inspect(1)](/skopeo-inspect/1.md), [tar(1)](/tar/1.md), container-registries.conf(5), [containers-storage.conf(5)](/containers-storage.conf/5.md)

## AUTHORS

Miloslav Trmač mitr@redhat.com ⟨mailto:mitr@redhat.com⟩ Valentin Rothberg rothberg@redhat.com ⟨mailto:rothberg@redhat.com⟩