4.2.14.3 LABEL Version Field
A focused guide to LABEL Version Field, connecting core concepts with practical Docker and container operations.
The LABEL version field records, directly within an image's own metadata, which version of the application or image it represents, providing a way to confirm exactly what version is present even without relying on the image's tag, which can be reassigned over time.
Setting a Version Label
A version label is typically set to match the same version the image is also tagged with, providing a redundant, more durable record of that version directly within the image's metadata.
LABEL version="2.3.0"
docker build -t myapp:2.3.0 --label version=2.3.0 .
The label can also be supplied directly at build time, rather than hardcoded in the Dockerfile, which is useful when the version is determined dynamically by a build pipeline.
Why a Version Label Provides Value Beyond the Tag
Because tags are mutable and can be reassigned, a version recorded as a label provides an additional, independent confirmation of what version an image actually represents, retrievable directly from the image regardless of what tag it might currently be referenced by.
docker inspect myapp@sha256:abc123... --format '{{index .Config.Labels "version"}}'
Even when referencing an image purely by digest, with no tag information at all, the version label remains directly retrievable.
Combining With Build Metadata for Full Traceability
A version label combined with a commit hash label provides strong traceability, letting anyone inspecting an image determine both its intended version and the exact source code it was built from.
ARG VERSION
ARG GIT_COMMIT
LABEL version=$VERSION
LABEL git.commit=$GIT_COMMIT
docker build --build-arg VERSION=2.3.0 --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t myapp:2.3.0 .
Why the Version Label Matters
Recording version information as a label provides a durable, independently verifiable record that survives even if an image's tag is later reassigned or the image is referenced purely by digest, making it a valuable supplement to tag-based versioning rather than a replacement for it.