Skip to main content
Version: 1.4.x


A repository rule to pull image layers using Bazel's downloader.

Typical usage in WORKSPACE.bazel:

load("@rules_oci//oci:pull.bzl", "oci_pull")

# A single-arch base image
name = "distroless_java",
digest = "sha256:161a1d97d592b3f1919801578c3a47c8e932071168a96267698f4b669c24c76d",
image = "",

# A multi-arch base image
name = "distroless_static",
digest = "sha256:c3c3d0230d487c0ad3a0d87ad03ee02ea2ff0b3dcce91ca06a1019e07de05f12",
image = "",
platforms = [

Now you can refer to these as a base layer in BUILD.bazel. The target is named the same as the external repo, so you can use a short label syntax:

name = "app",
base = "@distroless_static",

Macros and Functions


Repository macro to fetch image manifest data from a remote docker registry.

To use the resulting image, you can use the @wkspc shorthand label, for example if name = "distroless_base", then you can just use base = "@distroless_base" in rules like oci_image.

This shorthand syntax is broken on the command-line prior to Bazel 6.2. See

Example usage (generated):

load("@rules_oci//oci:pull.bzl", "oci_pull")

# repository with this name is created
name = "",



repository with this name is created


Optional. Default: None

the remote image, such as A tag can be suffixed with a colon, like debian:latest, and a digest can be suffixed with an at-sign, like debian@sha256:e822570981e13a6ef1efcf31870726fbd62e72d9abfdcf405a9d8f566e8d7028.

Exactly one of image or {registry,repository} should be set.


Optional. Default: None

the image path beneath the registry, such as distroless/static. When set, registry must be set as well.


Optional. Default: None

the remote registry domain, such as or When set, repository must be set as well.


Optional. Default: None

for multi-architecture images, a dictionary of the platforms it supports This creates a separate external repository for each platform, avoiding fetching layers.


Optional. Default: None

the digest string, starting with "sha256:", "sha512:", etc. If omitted, instructions for pinning are provided.


Optional. Default: None

a tag to choose an image from the registry. Exactly one of tag and digest must be set. Since tags are mutable, this is not reproducible, so a warning is printed.


Optional. Default: True

Set to False to silence the warning about reproducibility when using tag.


Optional. Default: False

whether the oci_pull is being called from a module extension