3.2.2.2 Semantic Image Tags
A focused guide to Semantic Image Tags, connecting core concepts with practical Docker and container operations.
Semantic image tags apply the conventions of semantic versioning — major, minor, and patch numbers, each with a defined meaning — to image tags, so that the tag itself communicates the nature and risk of the change between one version and the next.
The Structure of Semantic Versioning
A semantic version tag typically takes the form major.minor.patch, where incrementing each part signals something specific: a major version bump indicates breaking changes, a minor version bump indicates new, backward-compatible functionality, and a patch bump indicates backward-compatible bug fixes.
docker build -t myapp:2.3.1 .
A consumer of this image can infer, from the tag alone, that this is a patch release on top of the 2.3.x line, without needing to consult separate release notes just to understand the nature of the change.
Tagging Multiple Levels of Specificity
Many projects tag a single build with several semantic tags simultaneously, allowing consumers to depend on whichever level of specificity suits their needs — an exact patch version, or a more general minor or major version line that is expected to receive compatible updates.
docker tag myapp:2.3.1 myapp:2.3
docker tag myapp:2.3.1 myapp:2
docker push myapp:2.3.1
docker push myapp:2.3
docker push myapp:2
A consumer depending on myapp:2 receives whatever the latest 2.x.y release happens to be, while a consumer depending on myapp:2.3.1 always receives that exact, specific version.
Communicating Compatibility Through Tags
Because the versioning scheme has agreed-upon meaning, a consumer can reason about whether upgrading to a new tag is likely to be safe without inspecting the image's actual contents — moving from 2.3.1 to 2.3.2 is expected to be safe, while moving from 2.x to 3.0.0 is expected to require some adaptation.
docker pull myapp:2.3
Why Semantic Tagging Matters
Semantic image tags turn a version number from an arbitrary label into a meaningful signal about compatibility and risk, which helps consumers of an image make informed decisions about when and how aggressively to adopt new versions, without needing to track detailed release notes for every single update.