Docker commands Guide – docker tag with examples

Here’s a complete tutorial on docker tag, covering what it does, examples, and use cases.

What is docker tag?

docker tag is a Docker command that creates a new tag (alias) for an existing Docker image. It does not create a new image but assigns a new name or version tag to an existing image ID. This is useful for version control, renaming images, or preparing images for deployment to a registry.

Key Features:

• Assign multiple tags to the same image.
• Rename images for better organization.
• Prepare images for publishing to Docker Hub or private registries.
• Helps with versioning and managing image lifecycle.

Basic Syntax

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]
Code language: CSS (css)

Arguments:

• SOURCE_IMAGE[:TAG]: The existing image and optional tag you want to rename.
• TARGET_IMAGE[:TAG]: The new name and optional tag for the image.

Examples of docker tag

1. Tag an Image with a New Version

docker tag my_app:latest my_app:v1.0
Code language: CSS (css)

This tags the my_app:latest image as my_app:v1.0.

2. Add a Repository Name for Pushing to Docker Hub

docker tag my_app:latest myusername/my_app:latest

This prepares my_app:latest for pushing to Docker Hub under myusername.

3. Tag an Image with a Different Registry

docker tag my_app:latest registry.example.com/my_app:latest

This tags the image for pushing to a private registry (registry.example.com).

4. Create Multiple Tags for the Same Image

docker tag my_app:latest my_app:stable
docker tag my_app:latest my_app:testing
Code language: CSS (css)

This creates multiple tags (stable and testing) for the same image.

5. Tag an Image by ID

docker tag a1b2c3d4e5f6 my_app:v2.0
Code language: CSS (css)

This tags the image with ID a1b2c3d4e5f6 as my_app:v2.0.

6. Rename an Image

docker tag old_name:latest new_name:latest
Code language: CSS (css)

This renames old_name:latest to new_name:latest.

7. Prepare an Image for Kubernetes Deployment

docker tag my_app:latest registry.example.com/project/my_app:v1.0.0

This tags the image for deployment to a Kubernetes cluster using a specific registry.

8. Use docker tag in Automation Scripts

#!/bin/bash
docker tag my_app:latest my_app:backup_$(date +%Y%m%d)
echo "Image tagged as my_app:backup_$(date +%Y%m%d)"
Code language: JavaScript (javascript)

This script tags the image with a timestamp.

9. Version Control with Semantic Tagging

docker tag my_app:latest my_app:1.0.0
docker tag my_app:latest my_app:1.0
docker tag my_app:latest my_app:1
Code language: CSS (css)

This helps maintain semantic versioning (major.minor.patch).

10. Tag a Multi-Architecture Image

If you are building for multiple architectures (linux/amd64, linux/arm64), tag each architecture-specific image:

docker tag my_app:arm64 my_app:latest-arm64
docker tag my_app:amd64 my_app:latest-amd64
Code language: CSS (css)

Use Cases for docker tag

1. Version Control and Image Management

• Tag images with version numbers for easy reference and rollback.
• Example: my_app:v1.0, my_app:v2.0.

2. Preparing Images for Deployment

• Add a tag for pushing images to Docker Hub or private registries.
• Example: myusername/my_app:latest.

3. Multi-Environment Workflows

• Tag images for different environments (development, staging, production).
• Example: my_app:dev, my_app:staging, my_app:prod.

4. Renaming Images

• Change image names for better organization or when switching repositories.
• Example: Rename old_app:latest to new_app:latest.

5. Automating CI/CD Pipelines

• Use docker tag in CI/CD pipelines to version and push images automatically.
• Example: Tagging with Git commit hashes or build numbers (my_app:build_123).

6. Backup and Rollback

• Create backup tags before making changes, allowing for easy rollback.
• Example: my_app:backup_20260207.

7. Multi-Registry Support

• Prepare images for multiple registries (Docker Hub, AWS ECR, Google Artifact Registry).
• Example: docker tag my_app:latest gcr.io/project/my_app:latest.

List of Common docker tag Commands

Best Practices for Using docker tag:

1. Follow semantic versioning (major.minor.patch) to maintain a clear image versioning strategy.
2. Use meaningful tags for different environments (dev, staging, prod).
3. Tag before pushing to a registry for clarity and traceability.
4. Automate tagging in CI/CD pipelines for consistent version control.
5. Avoid ambiguous tags like latest in production—always prefer versioned tags.

Common Errors and Solutions

1. “No such image”
   → Ensure the source image exists. Use docker images to verify.
2. “Image is already tagged”
   → This is a warning, not an error. You can re-tag an image with different tags.
3. “Repository name must be lowercase”
   → Docker image names must be lowercase (e.g., my_app, not My_App).

Combining docker tag with Other Commands

Push Tagged Images to Docker Hub

docker tag my_app:latest myusername/my_app:latest
docker push myusername/my_app:latest

Automate Versioning in CI/CD

docker build -t my_app:latest .
docker tag my_app:latest my_app:v1.0.0
docker push my_app:v1.0.0
Code language: CSS (css)

Rollback to a Previous Version

docker tag my_app:v1.0 my_app:latest
docker run my_app:latest
Code language: CSS (css)

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.