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-readablerepository:tagidentifier..: 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
Build an image without a tag (creates an untagged image).
console$ docker build .
Build the same image again with a staging tag.
console$ docker build -t myapp:staging .
Create another tag for the production environment.
console$ docker build -t myapp:production .
List Docker images to view tagged and untagged entries.
console$ docker image ls
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 206MBBy 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
Tag an untagged image using its image ID.
console$ docker image tag 6410385feccb myapp:dev
6410385feccb: The image ID of the untagged image.myapp:dev: New tag to assign.
Tag an existing image with another version.
console$ docker image tag myapp:production myapp:v1.0
This creates a new tag
v1.0pointing to the same image asmyapp:production.Verify that both tags now reference the same image.
console$ docker image ls
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 206MBDocker 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
List current Docker images.
console$ docker image ls
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 206MBRemove previous versions before rebuilding.
console$ docker image rm myapp:staging myapp:production myapp:dev myapp:v1.0
Output.
Untagged: myapp:staging Untagged: myapp:production Untagged: myapp:dev Untagged: myapp:v1.0 Deleted: sha256:<image_id>Build a new image with all required tags.
console$ docker build -t myapp:staging -t myapp:production -t myapp:dev -t myapp:v1.0 .
Confirm the new image and tags.
console$ docker image ls
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 206MBAll 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.3to clearly represent major, minor, and patch versions.Major/Base Version Tags: Tags like
repository:1,repository:2help track long-term support and major milestones.Feature Tags: Use tags such as
repository:lightwoodorrepository:huggingfaceto 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-paymentMaintain 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.
No comments yet.