remove_image

remove_image(image_name: str, root: str | PathLike | Path = None) → Optional[str]

Remove one image ref from the Local Registry.

This removes only the mutable local ref. Immutable manifest and payload blobs remain available to other refs and are reclaimed by gc() once unreachable. Returns the atomically removed Manifest digest, or None when the ref did not exist. Pass that digest to restore_image() to roll back this exact deletion.

An invalid image reference raises ValueError. Registry and storage failures raise RuntimeError.