pull.md

Public API for pulling base container images.

pull

load("@rules_img//img:pull.bzl", "pull")

pull(name, credential_helper, digest, docker_config_path, downloader, layer_handling, platforms,
     registries, registry, repository, tag, unsafe_allow_tag_without_digest)

Pulls a container image from a registry using shallow pulling.

This repository rule implements shallow pulling - it only downloads the image manifest and config, not the actual layer blobs. The layers are downloaded on-demand during push operations or when explicitly needed. This significantly reduces bandwidth usage and speeds up builds, especially for large base images.

Example usage in MODULE.bazel:

pull = use_repo_rule("@rules_img//img:pull.bzl", "pull")

pull(
    name = "ubuntu",
    digest = "sha256:1e622c5f073b4f6bfad6632f2616c7f59ef256e96fe78bf6a595d1dc4376ac02",
    registry = "index.docker.io",
    repository = "library/ubuntu",
    tag = "24.04",
)

The digest parameter is recommended for reproducible builds. If omitted, the rule will resolve the tag to a digest at fetch time and print a warning.

By default, all child manifests of a multi-platform image index are downloaded. Use the platforms attribute to restrict the pull to the platforms you build for.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
credential_helper	Credential helper to use for registry authentication when this repository rule runs the pull tool. If omitted, the pull tool inherits $IMG_CREDENTIAL_HELPER (or $IMG_CREDENTIAL_HELPER_OCI_REGISTRY, which takes precedence) when present.	String	optional	""
digest	The image digest for reproducible pulls (e.g., "sha256:abc123..."). When specified, the image is pulled by digest instead of tag, ensuring reproducible builds. The digest must be a full SHA256 digest starting with "sha256:".	String	optional	""
docker_config_path	Path to Docker-compatible registry authentication config. If omitted, the pull tool inherits $REGISTRY_AUTH_FILE when present.	String	optional	""
downloader	The tool to use for downloading manifests and blobs. Available options: * img_tool (default): Uses the img tool for all downloads. * bazel: Uses Bazel's native HTTP capabilities for downloading manifests and blobs.	String	optional	"img_tool"
layer_handling	Strategy for handling image layers. This attribute controls when and how layer data is fetched from the registry. Available strategies: * shallow (default): Layer data is fetched only if needed during push operations, but is not available during the build. This is the most efficient option for images that are only used as base images for pushing. * eager: Layer data is fetched in the repository rule and is always available. This ensures layers are accessible in build actions but is inefficient as all layers are downloaded regardless of whether they're needed. Use this for base images that need to be read or inspected during the build. * lazy: Layer data is downloaded in a build action when requested. This provides access to layers during builds while avoiding unnecessary downloads, but requires network access during the build phase. EXPERIMENTAL: Use at your own risk.	String	optional	"shallow"
platforms	Platforms to download from a multi-platform image index. Each entry is an "os/architecture" or "os/architecture/variant" string (e.g. ["linux/amd64", "linux/arm64"]). Platforms are normalized before they are compared, so "linux/arm64" also matches an index entry declaring arm64 with variant v8. An entry that names no variant matches every variant of that OS/architecture, so adding this attribute never changes which child manifest a build ends up using - it only drops the platforms you did not list. Name a variant ("linux/amd64/v3") to select just that one. If omitted (the default), every child manifest of the index is downloaded. Since a registry counts each child manifest as a separate pull, restricting the list to the platforms you actually build for can cut a cold fetch of a typical multi-arch base image from tens of requests to a handful. Attestation manifests (which buildkit publishes with the platform unknown/unknown) are dropped unless "unknown/unknown" is listed explicitly. Fetching fails if a requested platform has no matching manifest in the index. The attribute has no effect when pulling a single-platform image (the digest refers to that manifest, so there is nothing to skip). Note: the index blob is stored verbatim, so it keeps listing every platform while only the selected children are available locally. A filtered image is meant to be used as a base image; pushing or loading its unmodified index is not supported.	List of strings	optional	[]
registries	List of mirror registries to try in order. These registries will be tried in order before the primary registry. Useful for corporate environments with registry mirrors or air-gapped setups.	List of strings	optional	[]
registry	Primary registry to pull from (e.g., "index.docker.io", "gcr.io"). If not specified, defaults to Docker Hub. Can be overridden by entries in registries list.	String	optional	""
repository	The image repository within the registry (e.g., "library/ubuntu", "my-project/my-image"). For Docker Hub, official images use "library/" prefix (e.g., "library/ubuntu").	String	required
tag	The image tag to pull (e.g., "latest", "24.04", "v1.2.3"). While required, it's recommended to also specify a digest for reproducible builds.	String	optional	""
unsafe_allow_tag_without_digest	Allow pulling by tag without specifying a digest. WARNING: This is not recommended for reproducible builds as tags can be moved to point to different image versions. Only use this when you're managing reproducibility through other means (e.g., content-based tags). When enabled, the rule will resolve the tag to a digest at fetch time and use that digest, but will not fail if no digest is explicitly provided.	Boolean	optional	False