Implementation:MaterializeInc Materialize Mz Image Tag Exists

Knowledge Sources	`misc/python/materialize/docker.py` (mz_image_tag_exists, mz_image_tag_exists_cmdline, image_registry)
Domains	Build Systems, Container Registries, Caching, CI/CD
Last Updated	2026-02-08

Overview

Concrete implementation of multi-tier container registry cache lookup provided by mz_image_tag_exists() and image_registry() in Materialize's docker utilities module.

Description

The registry cache lookup implementation consists of three cooperating functions:

1. mz_image_tag_exists(image_tag, quiet=False) (lines 67-113): The primary entry point that checks whether a Materialize Docker image exists at a given tag. It implements a multi-tier lookup strategy:

In-memory cache -- Checks EXISTENCE_OF_IMAGE_NAMES_FROM_EARLIER_CHECK dictionary for a previously cached result.
Local Docker daemon -- Runs docker images --quiet {image_name} to check if the image exists locally.
Docker Hub REST API -- For the default materialize registry, queries https://hub.docker.com/v2/repositories/materialize/materialized/tags/{tag} to avoid rate limit consumption.
Fallback to CLI -- For non-default registries (e.g., GHCR) or on API errors, falls back to mz_image_tag_exists_cmdline().

2. mz_image_tag_exists_cmdline(image_name) (lines 46-64): A fallback that uses docker manifest inspect to check image existence. Parses the output to distinguish "not found" from other errors, and caches only definitive results.

3. image_registry() (lines 213-218): Returns the active container registry based on the MZ_GHCR environment variable. Returns "ghcr.io/materializeinc/materialize" when enabled (default in CI), or "materialize" (Docker Hub) otherwise.

Usage

Use these functions when:

Checking if an image needs to be built -- Before triggering an expensive Rust compilation and Docker build, verify the image does not already exist.
Implementing the acquire() workflow -- The DependencySet.acquire() method uses this pattern to decide whether to pull or build each image.
Implementing the ensure() workflow -- The DependencySet.ensure() method checks publication status before building.
Determining which registry to query -- Use image_registry() to resolve the correct registry endpoint.

Code Reference

Source Location

File	`misc/python/materialize/docker.py`
`mz_image_tag_exists`	Lines 67-113
`mz_image_tag_exists_cmdline`	Lines 46-64
`image_registry`	Lines 213-218

Signature

def mz_image_tag_exists(image_tag: str, quiet: bool = False) -> bool:
    ...

def mz_image_tag_exists_cmdline(image_name: str) -> bool:
    ...

def image_registry() -> str:
    ...

Import

from materialize.docker import mz_image_tag_exists, image_registry

I/O Contract

Inputs

Parameter	Type	Description
`image_tag` (mz_image_tag_exists)	`str`	The Docker image tag to check (e.g., `"mzbuild-ABCDE..."` or `"v0.114.0"`).
`quiet` (mz_image_tag_exists)	`bool`	If `True`, suppresses informational print statements. Default: `False`.
`image_name` (mz_image_tag_exists_cmdline)	`str`	Fully qualified image name including registry (e.g., `"materialize/materialized:v0.114.0"`).
`MZ_GHCR` env var (image_registry)	`str`	Environment variable controlling registry selection. Defaults to `"1"` in CI, `"0"` otherwise.

Outputs

Output	Type	Description
Return value (mz_image_tag_exists)	`bool`	`True` if the image exists (locally or remotely), `False` otherwise.
Return value (mz_image_tag_exists_cmdline)	`bool`	`True` if `docker manifest inspect` succeeds, `False` otherwise.
Return value (image_registry)	`str`	Either `"ghcr.io/materializeinc/materialize"` or `"materialize"`.
Side effect: cache population	`dict[str, bool]`	`EXISTENCE_OF_IMAGE_NAMES_FROM_EARLIER_CHECK` is updated with the result for future lookups.

Usage Examples

Basic image existence check:

from materialize.docker import mz_image_tag_exists, image_registry

# Check if a fingerprint-tagged image exists
tag = f"mzbuild-{fingerprint}"
if mz_image_tag_exists(tag):
    print("Image found -- skipping build")
else:
    print("Image not found -- building from source")

Checking a release version:

from materialize.docker import mz_image_tag_exists

# Check for a release image
exists = mz_image_tag_exists("v0.114.0", quiet=True)

Registry selection:

from materialize.docker import image_registry

registry = image_registry()
# In CI (MZ_GHCR=1): "ghcr.io/materializeinc/materialize"
# Locally (MZ_GHCR=0): "materialize"

full_image_name = f"{registry}/materialized:v0.114.0"

Understanding the multi-tier lookup flow:

# Tier 1: Check in-memory cache
#   EXISTENCE_OF_IMAGE_NAMES_FROM_EARLIER_CHECK[image_name]
#   -> Returns cached bool if present

# Tier 2: Check local Docker daemon
#   docker images --quiet {image_name}
#   -> If output is non-empty, image exists locally

# Tier 3: Query Docker Hub REST API (only for "materialize" registry)
#   GET https://hub.docker.com/v2/repositories/materialize/materialized/tags/{tag}
#   -> Check response JSON for "images" key

# Tier 4: Fallback to docker manifest inspect (for GHCR or API errors)
#   docker manifest inspect {image_name}
#   -> Parse stderr for "no such manifest:" to distinguish not-found from errors

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment