crane-delete

Delete an image reference from its registry

$ crane delete [image_name]

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

crane delete <REFERENCE> [flags]

    The image reference to delete. This can be a tag (e.g., myregistry/myimage:mytag) or a digest (e.g., myregistry/myimage@sha256:digestvalue).

--help, -h
    Show help for the delete command.

--insecure
    Allow insecure connections to the registry, such as HTTP or HTTPS with unverified certificates. Use with caution.

--platform strings
    Specify the operating system and architecture of the image to delete (e.g., linux/amd64). Useful when deleting specific manifests from a multi-platform manifest list. Can be specified multiple times.

--registry-insecure
    Deprecated. Use --insecure instead. Allows insecure connections to the registry.

--repo string
    Explicitly specify the repository to delete from. If not provided, it is inferred from the image reference.

The crane delete command is a subcommand of the crane CLI tool, developed by GoogleContainerTools. It provides a robust way to remove container images, manifest lists, or specific image manifests from OCI (Open Container Initiative) compliant registries such as Docker Hub, Quay.io, or Google Container Registry.

Unlike local image deletion commands (e.g., docker rmi), crane delete interacts directly with the remote registry API. This is particularly useful for automation, scripting, and managing registry storage without needing a local Docker daemon. It can delete images referenced by tag or by digest. Deleting by digest ensures the exact manifest is removed, which is crucial for managing multi-platform images or ensuring specific versions are purged. While the command initiates the deletion, the actual freeing of storage space on the registry side often depends on the registry's garbage collection process, which may not be immediate.

Irreversible Action: Deleting an image from a registry is typically irreversible. Once the manifest is removed, recovery is generally not possible.

Registry Garbage Collection: While crane delete removes the manifest entry, the actual disk space occupied by the image layers might not be freed immediately. Registries often have a garbage collection process that runs periodically to clean up orphaned layers.

Authentication: Proper authentication to the registry is required. crane often reuses credentials from ~/.docker/config.json or environment variables, but incorrect or insufficient permissions will result in deletion failure.

Multi-platform Images: When deleting a tag that points to a manifest list, ensure you understand if you are deleting the entire list or specific platform manifests within it. Deleting by digest is often more precise.

crane delete, like other crane commands, handles registry authentication by default by checking the ~/.docker/config.json file for stored credentials. Alternatively, credentials can be provided via environment variables (e.g., CRANE_USERNAME, CRANE_PASSWORD), or through specific cloud provider authentication mechanisms if crane has built-in support (e.g., GCR, ECR).

When deleting, it's important to understand the difference between referencing an image by tag (e.g., myimage:latest) and by digest (e.g., myimage@sha256:...). Deleting by tag removes the tag's pointer to a manifest. The manifest itself (and its layers) might still exist if other tags or manifest lists point to it. Deleting by digest directly targets and removes a specific manifest. This is generally preferred for precise deletions, especially for immutable image versions or specific platform variants within a manifest list.

The crane tool, including its delete subcommand, was developed by GoogleContainerTools as an open-source project. It emerged as a powerful, Go-based alternative to traditional container tooling for direct interaction with OCI registries. Its design focuses on speed, simplicity, and direct API interaction, bypassing local Docker daemons. The delete command has been a core functionality since early versions of crane, addressing the need for efficient remote image management and cleanup.

crane pull (subcommand of crane tool), crane push (subcommand of crane tool), crane ls (subcommand of crane tool), skopeo delete (part of skopeo(1)), docker rmi (part of docker(1)), podman rmi (part of podman(1))