# How to Tag a Container Image Using the `container image tag` Command

> Learn to tag a container image for free with apple/container image tag. This guide explains how to add a new reference without duplicating layers.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-07-12

---

**The `container image tag` command creates an additional reference (tag) for an existing container image without duplicating underlying layers by constructing an `ImageTransfer` request processed by the `BuildImageResolver`.**

The apple/container repository provides a lightweight Container CLI for managing container images locally. When you need to assign an additional name or version identifier to an existing image, the `container image tag` command allows you to create these references efficiently. This guide explains the command syntax, internal implementation details, and practical usage based on the actual source code.

## Understanding the `container image tag` Command

The `container image tag` sub-command generates a new reference for an existing container image without altering the original image data. According to the command reference in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), this operation creates an alias that points to the same underlying image layers as the original reference.

When executed, the command validates that both source and target arguments are supplied. It then constructs an internal request structure that maps the existing image reference to the new target reference.

## Command Syntax and Usage

The basic syntax requires two arguments: the source image reference and the target reference.

```bash
container image tag <source> <target>

```

For example, to tag a local Alpine image with a new repository name:

```bash
container image tag alpine:latest myrepo/alpine:stable

```

You can also retag remote images without explicitly pulling them first:

```bash
container image tag registry.example.com/fido/web-test:1.0 registry.example.com/fido/web-test:latest

```

## Internal Implementation with ImageTransfer

When you execute the tag command, the CLI builds an **ImageTransfer** request internally. As implemented in [`Sources/ContainerBuild/BuildImageResolver.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildImageResolver.swift), this structure carries:

- The source reference (`ref`)
- A tag derived from the image's digest
- Metadata containing the new target reference

The `ImageTransfer` initializer (lines 19-33) validates these fields and returns an `imageTagMissing` error if the tag metadata is absent (lines 41-44 in [`BuildImageResolver.swift`](https://github.com/apple/container/blob/main/BuildImageResolver.swift)).

### The BuildImageResolver Component

The **BuildImageResolver** processes the transfer request by validating the presence of required metadata. If validation passes, the system records the new reference in the local image store while preserving the original reference untouched.

## Testing and Validation

The integration test suite provides a helper method that demonstrates the exact CLI invocation. In `Tests/IntegrationTests/Utilities/ContainerFixture+ImageHelpers.swift`, the `doImageTag` method wraps the command:

```swift
func doImageTag(_ image: String, newName: String) throws {
    try run(["image", "tag", image, newName]).check()
}

```

This helper confirms that the CLI accepts the standard `image tag` subcommand syntax and validates that the operation succeeds.

## Verifying Tagged Images

After tagging, both references point to the same underlying image data. Running `container image list` or `container image inspect` displays both the original and newly created tags, confirming they share identical digests.

## Summary

- The `container image tag` command creates additional references without duplicating image data or modifying layers
- Internally, the command constructs an `ImageTransfer` request processed by `BuildImageResolver` in [`Sources/ContainerBuild/BuildImageResolver.swift`](https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildImageResolver.swift)
- Validation ensures the `imageTagMissing` error is thrown if tag metadata is absent from the request
- The test helper in `Tests/IntegrationTests/Utilities/ContainerFixture+ImageHelpers.swift` demonstrates the exact CLI invocation pattern
- Both original and new references appear in `container image list` output, pointing to the same underlying image

## Frequently Asked Questions

### Does tagging a container image duplicate the underlying storage?

No. Tagging creates a new reference pointing to the same image layers without copying data. The `ImageTransfer` mechanism in [`BuildImageResolver.swift`](https://github.com/apple/container/blob/main/BuildImageResolver.swift) only records the new reference in the local image store metadata, leaving the original reference intact.

### What happens if I try to tag a non-existent image?

The CLI validates the source reference before constructing the `ImageTransfer` request. If the source image is missing or the tag metadata is absent, the resolver returns an `imageTagMissing` error as defined in [`BuildImageResolver.swift`](https://github.com/apple/container/blob/main/BuildImageResolver.swift) (lines 41-44).

### Can I use the test helper in my own Swift code?

Yes. The `doImageTag` method in `Tests/IntegrationTests/Utilities/ContainerFixture+ImageHelpers.swift` demonstrates how to programmatically invoke the tag command. You can adapt this pattern for custom integration testing by calling the CLI with the `["image", "tag", source, target]` argument array.

### Is the `container image tag` command compatible with remote registries?

Yes. The command handles both local and remote images. If the source reference points to a remote registry, the CLI fetches the image if needed before applying the tag, as documented in the command reference and demonstrated in the integration test utilities.