3.1.3.1 Immutable Image Artifact
A focused guide to Immutable Image Artifact, connecting core concepts with practical Docker and container operations.
An immutable image artifact is a built image treated as a fixed, unchangeable unit throughout its entire lifecycle — built once, stored, distributed, and deployed without modification, with any needed change resulting in an entirely new artifact rather than an edit to the existing one.
Treating the Artifact as Fixed After Build
Once an image is built and tagged for release, the artifact itself is not altered further; any fix or update results in a new build, tagged distinctly, leaving the original artifact intact and still available.
docker build -t registry.example.com/myapp:2.3.0 .
docker push registry.example.com/myapp:2.3.0
This artifact, once pushed, is treated as final — a bug discovered afterward is fixed by building and pushing 2.3.1, not by somehow altering 2.3.0 in place.
Why Treating Images as Fixed Artifacts Matters
Treating an image as a fixed artifact rather than something that might be patched in place means every environment that has pulled a given tag can trust that its contents will not change unexpectedly underneath it, which is essential for predictable behavior across distributed deployments.
docker pull registry.example.com/myapp:2.3.0
Pulling this tag today and pulling it again next month should retrieve the exact same content, assuming the tag itself has not been deliberately reassigned to point at different content.
Avoiding Mutable Tags in Practice
While tags can technically be reassigned, treating a released version's tag as immutable — never reusing it for different content — is a deliberate practice that preserves the reliability benefit of the underlying immutable artifact model.
docker tag myapp:2.3.0 myapp:2.3.0
Reassigning an already-released tag like this undermines the trust that environments place in that tag referring to consistent content, which is why many teams treat version tags as write-once in practice, even though Docker itself does not enforce this.
Why This Discipline Matters Operationally
Treating built images as immutable artifacts, both technically (via content digests) and as a matter of team practice (never reassigning released tags), is what allows deployment, rollback, and auditing processes to rely on a tag or digest as a trustworthy, stable reference to one specific, known set of contents.