3.1.3 Image Immutability
A focused guide to Image Immutability, connecting core concepts with practical Docker and container operations.
Image immutability means that once an image is built and assigned a content digest, its contents never change — any modification, however small, produces an entirely new image with a different digest, leaving the original image exactly as it was.
Why Images Cannot Be Modified in Place
Because an image's digest is computed from its actual content, changing that content would necessarily change its digest, meaning there is no such thing as "editing" an existing image — there is only ever building a new one, which may or may not share most of its layers with the original.
docker inspect myapp:1.0 --format '{{.Id}}'
docker build -t myapp:1.0 .
docker inspect myapp:1.0 --format '{{.Id}}'
If the build context changed at all between these two inspections, the reported digest differs, confirming that the tag myapp:1.0 now points to genuinely different image content than it did before.
Tags Can Move, Images Cannot Change
It is the tag, not the image, that is mutable — a tag like myapp:latest can be reassigned to point at a newer image over time, but each specific image it has ever pointed to remains permanently unchanged and independently retrievable by its own digest.
docker pull myapp@sha256:abc123...
Pulling by digest retrieves one exact, immutable image, regardless of what any tag currently points to.
Why Immutability Matters for Reliability
Immutability is what guarantees that an image deployed today will behave identically if deployed again next year, as long as it is referenced by its digest rather than by a tag that might have since been reassigned — this is the basis for genuinely reproducible deployments.
docker run myapp@sha256:abc123...
Immutability and Rollback
Because previous image versions remain unchanged and available, rolling back to an earlier version is simply running an earlier, still-intact image again, with full confidence that it has not been altered since it was last used.
docker run -d registry.example.com/myapp:2.2.9
Why This Property Matters
Image immutability is foundational to nearly every other reliability guarantee Docker provides — reproducible builds, dependable rollback, and trustworthy deployment all rest on the simple fact that an image, once built, simply cannot change underneath you.