How to Tag and Retag Docker Images

In this tutorial, you'll learn about How to Tag and Retag Docker Images. We cover key concepts, practical examples, and best practices.

The Problem

You build a Docker image and need to push it to a registry, but the image name doesn't match the registry URL format. Or you want to version-tag a build without rebuilding. Docker tags are aliases to the same image ID — you can add, remove, and move them without copying data. A single image can have multiple tags pointing to it, and deleting a tag only removes that reference, not the image data (until the last tag is removed).

Quick Fix

1. Tag an existing image

docker tag my-app:latest my-registry.com/my-app:v1.0.0

This adds a new tag pointing to the same image. No data is copied — tags are lightweight references. The image now has two names: my-app:latest and my-registry.com/my-app:v1.0.0.

2. Verify tags on the same image

docker images --filter "reference=my-app"

Expected output:

REPOSITORY          TAG       IMAGE ID       CREATED         SIZE
my-app              latest    abc123def456   2 hours ago     234MB
my-registry.com/    v1.0.0    abc123def456   2 hours ago     234MB

Both entries share the same IMAGE ID, confirming they're the same image.

3. Tag during docker build

docker build -t my-app:latest -t my-app:v1.0.0 .

The -t flag can be specified multiple times to add multiple tags at build time.

4. Retag to change a version tag

# Remove the old tag, add a new one (both pointing to the same image)
docker tag my-app:v1.0.0 my-app:stable
docker rmi my-app:v1.0.0

The image is only deleted when the last tag is removed. docker rmi removes only the tag, not the underlying image (unless it's the only tag).

5. Push a tagged image to a registry

docker push my-registry.com/my-app:v1.0.0

The registry URL format is registry-host:port/repository:tag. For Docker Hub, use username/repo:tag. For a private registry, use hostname:5000/repo:tag.

6. List all tags for an image

docker images --format "{{.Repository}}:{{.Tag}}" --filter "reference=*my-app*"

Expected output:

my-app:latest
my-app:v1.0.0
my-app:stable

7. Batch tag for multiple registries

for tag in latest v1.0.0 stable; do
  docker tag my-app:$tag prod-registry.com/my-app:$tag
done

8. Inspect all tags for a single image

docker images --digests --filter "reference=my-app"

Expected output:

REPOSITORY   TAG       DIGEST              IMAGE ID       CREATED       SIZE
my-app       latest    sha256:abc...       abc123def456   2 hours ago   234MB
my-app       v1.0.0    sha256:abc...       abc123def456   2 hours ago   234MB

The same DIGEST confirms both tags point to the same image.

9. Tag with date and commit SHA for CI/CD traceability

docker build -t my-app:$(date +%Y%m%d)-$(git rev-parse --short HEAD) .

This creates a unique tag like my-app:20250623-a1b2c3d that is both human-readable and traceable to the exact source code commit.

Prevention

• Use semantic versioning (v1.0.0, v1.1.0) for release tags
• Use latest as a convenience alias, not as the only tag
• Tag with the commit SHA in CI/CD for traceability
• Never tag an image with :latest if it's a breaking change
• Remove dangling tags with docker image prune to avoid confusion
• Inspect image digests to confirm tags point to the same image