Docker Image Tagging: A Complete Guide for Beginners

Tagging is one of Docker's most important features for organizing and versioning container images. Whether you're using official images from Docker Hub or creating your own custom images, understanding tags is essential for efficient container management.

In this guide, we'll cover:

• What is a Docker Image Tag?
• Tagging Official Images (e.g., nginx, ubuntu)
• Tagging Custom Images (your own applications)
• Best Practices for Versioning with Tags

What is a Docker Image Tag?

A Docker tag is a label assigned to an image that helps identify different versions of the same image. Tags follow this format:

IMAGE_NAME:TAG

• IMAGE_NAME → The repository name (e.g., nginx, my-app)
• TAG → A version identifier (e.g., latest, 1.0, v2.3.1)

If no tag is specified, Docker defaults to latest.

Tagging Official Docker Images

Official images (e.g., nginx, ubuntu, python) follow a structured tagging system to indicate different versions and variants.

1. Default Tags

• latest → The most recent stable release.

  docker pull nginx:latest
  

• Version-specific → Explicit version numbers.

  docker pull ubuntu:20.04
  docker pull python:3.9
  

2. Variant Tags (OS & Size Optimizations)

Official images often provide lightweight variants:

• -alpine → Smaller images based on Alpine Linux.

  docker pull nginx:alpine
  

• -slim → Stripped-down versions (fewer pre-installed packages).

  docker pull python:3.9-slim
  

3. Multi-Architecture Tags

Some tags support multiple CPU architectures (e.g., amd64, arm64):

docker pull --platform linux/arm64 ubuntu:20.04

Tagging Custom Docker Images

When building your own images, you should assign meaningful tags for version control.

1. Basic Tagging

Tag your image during the build process:

docker build -t my-app:1.0 .

• my-app → Repository name.
• 1.0 → Version tag.

2. Adding Multiple Tags

You can assign multiple tags to the same image:

docker tag my-app:1.0 my-app:latest
docker tag my-app:1.0 my-app:stable

3. Semantic Versioning (Recommended)

Use MAJOR.MINOR.PATCH for better tracking:

docker build -t my-app:2.1.0 .

• 2 → Major version (breaking changes)
• 1 → Minor version (new features)
• 0 → Patch version (bug fixes)

4. Using Git Commit Hashes

For CI/CD pipelines, you can tag images with Git commit IDs:

docker build -t my-app:$(git rev-parse --short HEAD) .

Example output:

my-app:abc1234

Best Practices for Docker Tagging

1. Avoid latest in Production

   • latest can change unexpectedly—use fixed versions (my-app:1.2.3).

2. Use Descriptive Tags

   • Example: backend-api:v2.3.1-prod

3. Clean Up Old Tags

   • Delete unused tags to save disk space:

     docker rmi my-app:old-version
     

4. Sign & Verify Images (Advanced)

   • Use Docker Content Trust (DOCKER_CONTENT_TRUST=1) to prevent untrusted images.

5. Tag Before Pushing to a Registry

   docker tag my-app:1.0 my-company/my-app:1.0
   docker push my-company/my-app:1.0
   

Conclusion

Key Takeaways

By following these tagging practices, you'll maintain better control over your Docker images, making deployments more reliable and traceable.

Happy Tagging! ️🐳