crane-pull

Pull remote image

$ crane pull [image_name] [path/to/tarball]

$ crane pull [image_name] [path/to/tarball] --annotate-ref

$ crane pull [image_name] [path/to/tarball] [[-c|--cache_path]] [path/to/cache]

$ crane pull [image_name] [path/to/tarball] [-format] [format_name]

$ crane pull [[-h|--help]]

`crane pull <source_image_reference> <destination_path> [options>]

Examples:
`crane pull gcr.io/google-containers/alpine:latest alpine.tar`
`crane pull --format=oci-archive myregistry/myimage:v1 myimage.oci`
`crane pull --platform=linux/arm64 registry.example.com/app:latest app-arm64/`

--format <format_type>
    Specifies the output format for the pulled image. Supported formats include `oci-archive` (a tar archive in OCI layout), `docker-archive` (a tar archive in Docker image format), and `oci` (an OCI layout directory). Default is `oci-archive`.

--platform <platform_spec>
    Selects a specific platform (e.g., `linux/amd64`, `windows/arm64`) from a multi-platform image manifest list to pull.

--insecure
    Allows connecting to registries over HTTP or with self-signed certificates, bypassing TLS verification.

--user-agent <agent_string>
    Overrides the default User-Agent header sent in HTTP requests to the registry.

--all
    When used with `--format=oci`, pulls all platforms described by a multi-platform manifest list into the destination directory.

The `crane pull` command is a subcommand of the crane utility, designed for efficiently downloading container images from OCI-compliant registries. It provides a flexible way to fetch image layers, manifests, and configurations, saving them to a local path in various formats. Unlike traditional container runtimes like Docker or Podman which often pull images into a local image store, `crane pull` writes the image directly to a specified local file or directory, making it ideal for CI/CD pipelines, image analysis, or transferring images without a local daemon. It supports authentication via standard Docker configuration files (`~/.docker/config.json`) and environment variables, and can handle multi-platform images, allowing users to specify a desired architecture. Its lightweight nature and direct interaction with registries make it a powerful tool for advanced image management.

`crane pull` is not a default Linux command; it requires the installation of the `crane` utility from the `go-containerregistry` project. Unlike `docker pull`, `crane pull` does not store images in a local daemon's image store; it writes them directly to disk. This means subsequent `docker run` commands won't automatically find images pulled by `crane pull` unless explicitly loaded (e.g., `docker load -i image.tar`). Be mindful of disk space, as pulled images can be large. Authentication for private registries relies on standard Docker credential helpers or environment variables, which must be configured correctly.

`crane` automatically attempts to use standard Docker credential helpers and configuration files (like `~/.docker/config.json`) for authenticating with private registries. Users can also configure credentials via environment variables such as `DOCKER_USERNAME`, `DOCKER_PASSWORD`, or `DOCKER_TOKEN` for specific registries.

• oci-archive: Creates a `.tar` archive of the image in OCI image layout specification format. This is the default.
• docker-archive: Creates a `.tar` archive of the image in the Docker image format, compatible with `docker load`.
• oci: Creates a directory structure representing the OCI image layout, rather than a single archive file. This is useful for direct inspection or modification of the image contents.

The `crane` tool is part of the `go-containerregistry` open-source project, initiated by Google. It was developed to provide a lightweight, programmatic way to interact with OCI and Docker registries using Go. The `crane` CLI, including the `pull` subcommand, emerged as a robust tool for performing low-level registry operations that might be cumbersome or impossible with higher-level container runtimes. Its focus on direct registry interaction and support for various image formats has made it popular in CI/CD environments and for specific image manipulation tasks outside the scope of typical `docker` or `podman` workflows.

crane(1), docker pull(1), podman pull(1), skopeo copy(1)