The remote package implements a client for accessing a registry, per the OCI distribution spec.

It leans heavily on the lower level transport package, which handles the authentication handshake and structured errors.


package main

import (

func main() {
	ref, err := name.ParseReference("")
	if err != nil {

	img, err := remote.Image(ref, remote.WithAuthFromKeychain(authn.DefaultKeychain))
	if err != nil {

	// do stuff with img



There are a lot of confusingly similar terms that come up when talking about images in registries.

Anatomy of an image

In general...

  • A tag refers to an image manifest.
  • An image manifest references a config file and an orderered list of compressed layers by sha256 digest.
  • A config file references an ordered list of uncompressed layers by sha256 digest and contains runtime configuration.
  • The sha256 digest of the config file is the image id for the image.

For example, an image with two layers would look something like this:

image anatomy

Anatomy of an index

In the normal case, an index is used to represent a multi-platform image. This was the original use case for a manifest list.

image index anatomy

It is possible for an index to reference another index, per the OCI image-spec. In theory, both an image and image index can reference arbitrary things via descriptors, e.g. see the image layout example, which references an application/xml file from an image index.

That could look something like this:

exotic image index anatomy

Using a recursive index like this might not be possible with all registries, but this flexibility allows for some interesting applications, e.g. the OCI Artifacts effort.

Anatomy of an image upload

The structure of an image requires a delicate ordering when uploading an image to a registry. Below is a (slightly simplified) figure that describes how an image is prepared for upload to a registry and how the data flows between various artifacts:


Note that:

  • A config file references the uncompressed layer contents by sha256.
  • A manifest references the compressed layer contents by sha256 and the size of the layer.
  • A manifest references the config file contents by sha256 and the size of the file.

It follows that during an upload, we need to upload layers before the config file, and we need to upload the config file before the manifest.

Sometimes, we know all of this information ahead of time, (e.g. when copying from remote.Image), so the ordering is less important.

In other cases, e.g. when using a stream.Layer, we can't compute anything until we have already uploaded the layer, so we need to be careful about ordering.


schema 1

This package does not support schema 1 images, see #377, however, it's possible to do something useful with them via remote.Get, which doesn't try to interpret what is returned by the registry.

crane.Copy takes advantage of this to implement support for copying schema 1 images, see here.

Expand ▾ Collapse ▴



    Package remote provides facilities for reading/writing v1.Images from/to a remote image registry.



    This section is empty.


    This section is empty.


    func Catalog

    func Catalog(ctx context.Context, target name.Registry, options ...Option) ([]string, error)

      Catalog calls /_catalog, returning the list of repositories on the registry.

      func CatalogPage

      func CatalogPage(target name.Registry, last string, n int, options ...Option) ([]string, error)

        CatalogPage calls /_catalog, returning the list of repositories on the registry.

        func CheckPushPermission

        func CheckPushPermission(ref name.Reference, kc authn.Keychain, t http.RoundTripper) error

          CheckPushPermission returns an error if the given keychain cannot authorize a push operation to the given ref.

          This can be useful to check whether the caller has permission to push an image before doing work to construct the image.

          TODO(#412): Remove the need for this method.

          func Delete

          func Delete(ref name.Reference, options ...Option) error

            Delete removes the specified image reference from the remote registry.

            func Head(ref name.Reference, options ...Option) (*v1.Descriptor, error)

              Head returns a v1.Descriptor for the given reference by issuing a HEAD request.

              Note that the server response will not have a body, so any errors encountered should be retried with Get to get more details.

              func Image

              func Image(ref name.Reference, options ...Option) (v1.Image, error)

                Image provides access to a remote image reference.

                func Index

                func Index(ref name.Reference, options ...Option) (v1.ImageIndex, error)

                  Index provides access to a remote index reference.

                  func Layer

                  func Layer(ref name.Digest, options ...Option) (v1.Layer, error)

                    Layer reads the given blob reference from a registry as a Layer. A blob reference here is just a punned name.Digest where the digest portion is the digest of the blob to be read and the repository portion is the repo where that blob lives.

                    func List

                    func List(repo name.Repository, options ...Option) ([]string, error)

                      List wraps ListWithContext using the background context.

                      func ListWithContext

                      func ListWithContext(ctx context.Context, repo name.Repository, options ...Option) ([]string, error)

                        ListWithContext calls /tags/list for the given repository, returning the list of tags in the "tags" property.

                        func MultiWrite

                        func MultiWrite(m map[name.Reference]Taggable, options ...Option) error

                          MultiWrite writes the given Images or ImageIndexes to the given refs, as efficiently as possible, by deduping shared layer blobs and uploading layers in parallel, then uploading all manifests in parallel.

                          Current limitations: - All refs must share the same repository. - Images cannot consist of stream.Layers.

                          func Tag

                          func Tag(tag name.Tag, t Taggable, options ...Option) error

                            Tag adds a tag to the given Taggable via PUT /v2/.../manifests/<tag>

                            Notable implementations of Taggable are v1.Image, v1.ImageIndex, and remote.Descriptor.

                            If t implements MediaType, we will use that for the Content-Type, otherwise we will default to types.DockerManifestSchema2.

                            Tag does not attempt to write anything other than the manifest, so callers should ensure that all blobs or manifests that are referenced by t exist in the target registry.

                            func Write

                            func Write(ref name.Reference, img v1.Image, options ...Option) error

                              Write pushes the provided img to the specified image reference.

                              func WriteIndex

                              func WriteIndex(ref name.Reference, ii v1.ImageIndex, options ...Option) error

                                WriteIndex pushes the provided ImageIndex to the specified image reference. WriteIndex will attempt to push all of the referenced manifests before attempting to push the ImageIndex, to retain referential integrity.

                                func WriteLayer

                                func WriteLayer(repo name.Repository, layer v1.Layer, options ...Option) error

                                  WriteLayer uploads the provided Layer to the specified repo.


                                  type Descriptor

                                  type Descriptor struct {
                                  	Manifest []byte
                                  	// contains filtered or unexported fields

                                    Descriptor provides access to metadata about remote artifact and accessors for efficiently converting it into a v1.Image or v1.ImageIndex.

                                    func Get

                                    func Get(ref name.Reference, options ...Option) (*Descriptor, error)

                                      Get returns a remote.Descriptor for the given reference. The response from the registry is left un-interpreted, for the most part. This is useful for querying what kind of artifact a reference represents.

                                      See Head if you don't need the response body.

                                      func (*Descriptor) Image

                                      func (d *Descriptor) Image() (v1.Image, error)

                                        Image converts the Descriptor into a v1.Image.

                                        If the fetched artifact is already an image, it will just return it.

                                        If the fetched artifact is an index, it will attempt to resolve the index to a child image with the appropriate platform.

                                        See WithPlatform to set the desired platform.

                                        func (*Descriptor) ImageIndex

                                        func (d *Descriptor) ImageIndex() (v1.ImageIndex, error)

                                          ImageIndex converts the Descriptor into a v1.ImageIndex.

                                          func (*Descriptor) RawManifest

                                          func (d *Descriptor) RawManifest() ([]byte, error)

                                            RawManifest exists to satisfy the Taggable interface.

                                            type ErrSchema1

                                            type ErrSchema1 struct {
                                            	// contains filtered or unexported fields

                                              ErrSchema1 indicates that we received a schema1 manifest from the registry. This library doesn't have plans to support this legacy image format:

                                              func (*ErrSchema1) Error

                                              func (e *ErrSchema1) Error() string

                                                Error implements error.

                                                type MountableLayer

                                                type MountableLayer struct {
                                                	Reference name.Reference

                                                  MountableLayer wraps a v1.Layer in a shim that enables the layer to be "mounted" when published to another registry.

                                                  func (*MountableLayer) Descriptor

                                                  func (ml *MountableLayer) Descriptor() (*v1.Descriptor, error)

                                                    Descriptor retains the original descriptor from an image manifest. See partial.Descriptor.

                                                    type Option

                                                    type Option func(*options) error

                                                      Option is a functional option for remote operations.

                                                      func WithAuth

                                                      func WithAuth(auth authn.Authenticator) Option

                                                        WithAuth is a functional option for overriding the default authenticator for remote operations.

                                                        The default authenticator is authn.Anonymous.

                                                        func WithAuthFromKeychain

                                                        func WithAuthFromKeychain(keys authn.Keychain) Option

                                                          WithAuthFromKeychain is a functional option for overriding the default authenticator for remote operations, using an authn.Keychain to find credentials.

                                                          The default authenticator is authn.Anonymous.

                                                          func WithContext

                                                          func WithContext(ctx context.Context) Option

                                                            WithContext is a functional option for setting the context in http requests performed by a given function. Note that this context is used for _all_ http requests, not just the initial volley. E.g., for remote.Image, the context will be set on http requests generated by subsequent calls to RawConfigFile() and even methods on layers returned by Layers().

                                                            The default context is context.Background().

                                                            func WithJobs

                                                            func WithJobs(jobs int) Option

                                                              WithJobs is a functional option for setting the parallelism of remote operations performed by a given function. Note that not all remote operations support parallelism.

                                                              The default value is 4.

                                                              func WithPlatform

                                                              func WithPlatform(p v1.Platform) Option

                                                                WithPlatform is a functional option for overriding the default platform that Image and Descriptor.Image use for resolving an index to an image.

                                                                The default platform is amd64/linux.

                                                                func WithTransport

                                                                func WithTransport(t http.RoundTripper) Option

                                                                  WithTransport is a functional option for overriding the default transport for remote operations.

                                                                  The default transport its http.DefaultTransport.

                                                                  func WithUserAgent

                                                                  func WithUserAgent(ua string) Option

                                                                    WithUserAgent adds the given string to the User-Agent header for any HTTP requests. This header will also include "go-containerregistry/${version}".

                                                                    If you want to completely overwrite the User-Agent header, use WithTransport.

                                                                    type Taggable

                                                                    type Taggable interface {
                                                                    	RawManifest() ([]byte, error)

                                                                      Taggable is an interface that enables a manifest PUT (e.g. for tagging).


                                                                      Path Synopsis
                                                                      Package transport provides facilities for setting up an authenticated http.RoundTripper given an Authenticator and base RoundTripper.
                                                                      Package transport provides facilities for setting up an authenticated http.RoundTripper given an Authenticator and base RoundTripper.