docker-image-tag

Assign a name and tag to a specific image ID

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

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

$ docker [[tag|image tag]]

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

--help
    Print detailed usage information

The docker image tag command (aliased as docker tag) creates a lightweight alias or reference for an existing Docker image, allowing it to be referenced by multiple names or tags without duplicating the underlying image layers. This is essential for versioning images, preparing them for registry pushes, or organizing local images.

It takes two main arguments: the source image (which can include a tag like nginx:1.21) and the target image name/tag (e.g., myregistry.com/nginx:v1). Both can be repository names, image IDs, or tagged references. Tagging is a metadata operation only—no data is copied, making it fast and efficient.

Common use cases include adding version tags before pushing to a registry, creating multi-arch tags, or renaming images for deployment. Tags follow semantic versioning or custom schemes, and repositories can include registry prefixes. After tagging, use docker image ls to verify.

This command supports image IDs (short or full SHA256 hashes) for sources without tags. It's non-destructive and reversible by removing tags with docker image rm.

Tagging creates only a reference—no image layers are duplicated. Removing a tag doesn't delete the image if other tags or digests reference it. Source must exist locally; no remote pulls. Tags are mutable unless pushed to an immutable registry.

docker image tag nginx mynginx
docker image tag nginx:latest myregistry.com/nginx:v1.21
docker image tag abc12345 nginx:testing

0: Success
1: General error (e.g., source not found)
125: Docker daemon unavailable

Introduced in early Docker versions (pre-1.0, around 2013) as part of core image management. Evolved with Docker CLI refactoring in v17.06 (2017), moving to subcommands like docker image. Alias docker tag retained for backward compatibility. Tracks Docker Engine releases tied to Moby project.

docker(1), docker-image-ls(1), docker-image-rm(1), docker-image-push(1), docker-tag(1)