docker-tag

Assign a name and tag to a specific image ID

$ docker tag [id] [name]:[tag]

$ docker tag [image]:[current_tag] [image]:[new_tag]

$ docker tag

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

SOURCE_IMAGE[:TAG]
    The name or ID of the existing image you wish to tag. Optionally, you can specify an existing tag for that image after a colon (e.g., ubuntu:18.04). If no tag is provided for the source, Docker will implicitly use :latest.

TARGET_IMAGE[:TAG]
    The new name (repository) and optionally a new tag you want to assign to the source image. The repository name can include a registry host (e.g., myregistry.com/my-app). If no tag is provided for the target, Docker will implicitly use :latest for the new tag.

The docker tag command creates an additional tag (or alias) for an existing Docker image. It does not create a new image nor does it duplicate any image layers. Instead, it simply creates a new pointer, or a new reference, to an existing image's unique identifier (ID).

This command is crucial for managing different versions of an image, or for preparing an image to be pushed to a specific Docker registry. For instance, you might build an image and initially tag it as my-app:dev. Once testing is complete, you can use docker tag to add another tag like my-app:v1.0 or myregistry.com/my-app:prod to the exact same image ID. This allows the same underlying image to be referenced by multiple names, making it easier to organize, deploy, and manage different stages or environments of your application.

While docker build -t can tag an image during its creation, docker tag is used to apply additional tags to an image that already exists on your local Docker daemon. It's a lightweight operation, as it only modifies metadata within the Docker image store, having no impact on disk space beyond the small amount needed for the tag itself.

The docker tag command only creates a local reference. To make the new tag available to others or on different machines, you must use docker push to upload the image with its new tag to a Docker registry.

If the TARGET_IMAGE[:TAG] already exists, docker tag will overwrite that existing tag, effectively pointing it to the SOURCE_IMAGE. This might cause the image previously pointed to by TARGET_IMAGE[:TAG] to become 'dangling' (untagged) if it has no other tags.

When you omit the :TAG part for the TARGET_IMAGE, Docker automatically assigns the tag :latest to the new reference. This means that docker tag myimage mynewimage is equivalent to docker tag myimage:latest mynewimage:latest (assuming myimage implicitly uses :latest as well).

Be cautious when tagging an image with a TARGET_IMAGE[:TAG] that already exists. The old image that was associated with that TARGET_IMAGE[:TAG] will no longer be referenced by it. If that old image has no other tags, it will become an untagged (dangling) image, which can then be cleaned up using docker image prune.

The docker tag command has been a fundamental part of Docker's command-line interface since its early days. Its core functionality, enabling users to create aliases or version indicators for their Docker images, has remained consistent and is indispensable for image lifecycle management, especially when integrating with continuous integration/continuous deployment (CI/CD) pipelines and public or private registries.

docker images(1), docker rmi(1), docker push(1), docker build(1)