How To Add a Tag to Docker Image

Docker tags let you assign meaningful names to container images, replacing unreadable IDs with clear, human-friendly references. This helps developers organize images by version, environment, or feature and ensures consistency across build, deployment, and collaboration workflows. In this article, you'll learn how to tag Docker images during and after the build process, apply multiple tags efficiently, and implement tagging best practices that integrate cleanly with version control and CI/CD pipelines.

The Short Answer Version

# Tag an image during build
$ docker build -t repository_name:tag .

# Tag an image after build
$ docker image tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

# Tag an image with multiple tags during build
$ docker build -t repository_name:tag1 -t repository_name:tag2 .

Tag a Docker Image During Build Process

You can assign a tag to a Docker image as soon as it’s built using the -t flag. This approach ensures the image is immediately labeled for its intended environment (e.g., staging or production), eliminating the need to re-tag it later.

Command Syntax

docker build -t repository_name:tag .

• docker build: Builds an image from the Dockerfile in the current directory.
• -t: Tags the image with a human-readable repository:tag identifier.
• .: Specifies the build context (usually the current directory).

You can extend it for multiple tags like:

docker build -t repository_name:tag1 -t repository_name:tag2 .

• -t repository_name:tag1: Applies the first tag.
• -t repository_name:tag2: Applies the second tag.

Command Demonstration

1. Build an image without a tag (creates an untagged image).

   CONSOLE

   Copy

   $ docker build .

   Explain Code

   Powered by Vultr AgentBeta

2. Build the same image again with a staging tag.

   CONSOLE

   Copy

   $ docker build -t myapp:staging .

   Explain Code

   Powered by Vultr AgentBeta

3. Create another tag for the production environment.

   CONSOLE

   Copy

   $ docker build -t myapp:production .

   Explain Code

   Powered by Vultr AgentBeta

4. List Docker images to view tagged and untagged entries.

   CONSOLE

   Copy

   $ docker image ls

   Explain Code

   Powered by Vultr AgentBeta

   Output.

   REPOSITORY   TAG          IMAGE ID       CREATED          SIZE
   myapp        production   459263adb890   19 minutes ago   206MB
   <none>       <none>       6410385feccb   19 minutes ago   206MB
   myapp        staging      38da9244f5f0   19 minutes ago   206MB

   By tagging during build, you avoid the ambiguity of unnamed images (<none>:<none>) and maintain clarity across environments.

Tag a Docker Image After Build Process

You can apply additional tags to an existing Docker image without rebuilding it. This is useful for versioning, staging, or applying environment-specific identifiers after the image is already built.

Command Syntax

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

• docker image tag: The command to create a new tag for an existing image.
• SOURCE_IMAGE[:TAG]: The current name or image ID of the Docker image.
• TARGET_IMAGE[:TAG]: The new tag to assign to the image.

Command Demonstration

1. Tag an untagged image using its image ID.

   CONSOLE

   Copy

   $ docker image tag 6410385feccb myapp:dev

   Explain Code

   Powered by Vultr AgentBeta
   • 6410385feccb: The image ID of the untagged image.
   • myapp:dev: New tag to assign.

2. Tag an existing image with another version.

   CONSOLE

   Copy

   $ docker image tag myapp:production myapp:v1.0

   Explain Code

   Powered by Vultr AgentBeta

   This creates a new tag v1.0 pointing to the same image as myapp:production.

3. Verify that both tags now reference the same image.

   CONSOLE

   Copy

   $ docker image ls

   Explain Code

   Powered by Vultr AgentBeta

   Output.

   REPOSITORY   TAG          IMAGE ID       CREATED             SIZE
   myapp        dev          6410385feccb   About an hour ago   206MB
   myapp        staging      38da9244f5f0   About an hour ago   206MB
   myapp        production   459263adb890   About an hour ago   206MB
   myapp        v1.0         459263adb890   About an hour ago   206MB

   Docker creates lightweight references when tagging, no duplicate data is stored. This lets you build once and tag for multiple workflows.

Build a Docker Image with Multiple Tags

You can assign multiple tags to a Docker image during the build process using the -t flag repeatedly. This avoids the need to re-tag images afterward and ensures consistent versioning for different environments.

Command Syntax

docker build -t repository_name:tag1 -t repository_name:tag2 [OPTIONS] PATH

• -t repository_name:tag1: First tag to assign.
• -t repository_name:tag2: Additional tag(s).
• PATH: Location of the Docker build context (commonly . for current directory).

Command Demonstration

1. List current Docker images.

   CONSOLE

   Copy

   $ docker image ls

   Explain Code

   Powered by Vultr AgentBeta

   Output.

   REPOSITORY   TAG          IMAGE ID       CREATED             SIZE
   myapp        dev          6410385feccb   About an hour ago   206MB
   myapp        staging      38da9244f5f0   About an hour ago   206MB
   myapp        production   459263adb890   About an hour ago   206MB
   myapp        v1.0         459263adb890   About an hour ago   206MB

2. Remove previous versions before rebuilding.

   CONSOLE

   Copy

   $ docker image rm myapp:staging myapp:production myapp:dev myapp:v1.0

   Explain Code

   Powered by Vultr AgentBeta

   Output.

   Untagged: myapp:staging
   Untagged: myapp:production
   Untagged: myapp:dev
   Untagged: myapp:v1.0
   Deleted: sha256:<image_id>

3. Build a new image with all required tags.

   CONSOLE

   Copy

   $ docker build -t myapp:staging -t myapp:production -t myapp:dev -t myapp:v1.0 .

   Explain Code

   Powered by Vultr AgentBeta

4. Confirm the new image and tags.

   CONSOLE

   Copy

   $ docker image ls

   Explain Code

   Powered by Vultr AgentBeta

   Output.

   REPOSITORY   TAG          IMAGE ID       CREATED             SIZE
   myapp        dev          83782771e2ab   Just now            206MB
   myapp        production   83782771e2ab   Just now            206MB
   myapp        staging      83782771e2ab   Just now            206MB
   myapp        v1.0         83782771e2ab   Just now            206MB

   All tags now point to the same image ID, confirming a single image was built with multiple references, an efficient practice for CI/CD pipelines or release workflows.

Docker Image Tagging Best Practices

Effective Docker tagging improves image traceability, deployment automation, and team collaboration. This section outlines a tagging toolbox and actionable strategies to ensure consistent and reliable image management.

Tag Types to Use

Adopt a flexible tagging scheme to support multiple release flows:

• Semantic Tags: Use repository:1.2.3 to clearly represent major, minor, and patch versions.

• Major/Base Version Tags: Tags like repository:1, repository:2 help track long-term support and major milestones.

• Feature Tags: Use tags such as repository:lightwood or repository:huggingface to highlight variant characteristics.

• Combined Tags: Combine version and context, e.g., repository:2.1-redis, for extra clarity.

• Build or Commit Tags: Useful in CI/CD pipelines, e.g., repository:74667932, repository:sha-abc123.

Avoid Using :latest in Production

Avoid relying on the latest tag in production environments. It can introduce unpredictability when different team members or systems pull images without knowing the exact version.

$ docker build -t app:2.1.0 .

Use explicit, versioned tags instead. Reserve :latest only for development or internal use.

Use Unique Tags for Each Deployment

Assign unique tags per build to ensure reproducibility. This helps with audit trails, rollback, and artifact management.

Examples:

app:build-92875462
app:20240521-1530
app:feature-payment

Maintain Stable Tags for Version Patching

Use stable tags for long-lived releases and minor updates. Update app:2.0 for security patches, and reassign latest to reflect the most recent stable version.

$ docker build -t app:2.0 -t app:latest .

Later, for a new minor release:

$ docker build -t app:2.1 -t app:latest .

Automate Tags with CI/CD Pipelines

Configure your CI/CD tools (e.g., GitHub Actions, Jenkins) to generate consistent and unique tags automatically.

- name: Build and Tag Docker Image
  run: |
    docker build -t myapp:${{ github.sha }} .
    docker tag myapp:${{ github.sha }} myapp:latest

Use commit hashes, branch names, or build IDs to ensure traceability.

Document and Enforce Tagging Conventions

Create and maintain a tagging guide in your repository. Define patterns for versioning, environments, and features.

# Tagging Strategy

Semantic Tags:
- app:1.2.3 → Patch release
- app:1.2   → Latest patch in minor line
- app:1     → Latest patch in major line

Feature Tags:
- app:redis   → Redis-enabled variant
- app:v2-graphql → v2 image with GraphQL support

Build Tags:
- app:dev-login
- app:build-74667932

Include this in your README.md or contribution guidelines.

Conclusion

In this article, you learned how to tag Docker images during and after the build process, assign multiple tags efficiently, and apply best practices for versioning and environment-specific image management. These techniques help streamline team workflows, improve deployment consistency, and support automated CI/CD pipelines.