A Docker build can work perfectly today and fail tomorrow, even when nobody has changed the application code or Dockerfile.
One common reason is an updated base image.
Most Dockerfiles start with a base image that provides the operating system, runtime, libraries, and tools required by the application. Developers often reference these images using tags such as alpine:3.21, node:22, or mcr.microsoft.com/dotnet/aspnet:10.0.
These tags are convenient, but they do not always identify an unchanging image. Publishers can update a tag to point to a newer image containing security patches, operating system updates, or other changes.
When a build downloads the updated image, the application may encounter unexpected behavior. A package might no longer be available, a system library might have changed, or a runtime update might expose an incompatibility.
The challenge is not that base images receive updates. Keeping them updated is essential for security. The challenge is allowing those updates into a production build without reviewing and testing their impact.
Docker provides several mechanisms for controlling this behavior, including image digests, explicit version tags, build options, and automated dependency updates.
Understanding Why Docker Base Images Change
A Docker image is built using layers. The base image provides the starting filesystem and environment, while subsequent Dockerfile instructions add application files, dependencies, and configuration.
Consider this Dockerfile:
FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY ./publish .
ENTRYPOINT ["dotnet", "MyApplication.dll"]
The application uses the .NET ASP.NET runtime image as its base.
The 10.0 tag identifies a release family, but it can point to different image contents over time.
For example, a publisher may update the image to include:
- Operating system security patches.
- Updated system libraries.
- Runtime servicing updates.
- Changes to installed utilities.
- Updated certificates or other system components.
When Docker resolves the same tag during a later build, it may download the updated image.
This is expected behavior for mutable tags.
The benefit is that developers can receive updates without manually changing the Dockerfile every time a publisher releases a patched image.
The downside is that two builds using the same Dockerfile may not necessarily use identical base image contents.
This can make builds harder to reproduce and introduce changes that have not been tested by the application team.
Understand the Difference Between Tags and Digests
Docker supports two common ways to reference an image: tags and digests.
A tag is a human-readable identifier assigned by the image publisher.
For example:
FROM alpine:3.21
This reference uses the 3.21 tag.
The publisher can update the tag to point to a newer patch release without changing the Dockerfile.
A digest identifies a specific image manifest or image index by its content hash.
For example:
FROM alpine:3.21@sha256:REPLACE_WITH_VERIFIED_DIGEST
The digest identifies the exact image content being referenced.
Even if the publisher moves the 3.21 tag to a newer image, the digest reference continues to identify the original image.
This makes digest references useful when build reproducibility matters.
The difference can be summarized as follows:
Reference | Behavior |
|---|
alpine:3.21 | Follows the image publisher's 3.21 tag |
alpine:3.21@sha256:... | Uses the specific image identified by the digest |
alpine:latest | Follows a mutable latest tag |
alpine@sha256:... | Uses the image identified by the digest without a tag |
A tag provides convenience, while a digest provides an immutable reference to specific image content.
Neither approach is universally better. The correct choice depends on how an organization balances reproducibility, security updates, and release control.
Pin Base Images to Digests for Reproducible Builds
If an application must use exactly the same base image until an update has been reviewed, pin the image to a digest.
Start by pulling the desired image:
docker pull alpine:3.21
Docker displays the image digest after the pull completes.
The output includes information similar to:
Digest: sha256:...
Status: Downloaded newer image
Use the actual digest returned by Docker in the Dockerfile:
FROM alpine:3.21@sha256:REPLACE_WITH_VERIFIED_DIGEST
WORKDIR /app
The placeholder must be replaced with the complete digest from the trusted registry. Do not copy an arbitrary digest from an example or another project.
You can also inspect an image reference using Docker Buildx:
docker buildx imagetools inspect alpine:3.21
This command displays image information, including its digest and available platform manifests.
For production applications, record the image reference used during each release. This makes it easier to investigate which base image was used when a particular application version was built.
One important trade-off is that digest pinning also prevents automatic adoption of security updates.
If a publisher releases a patched image, your Dockerfile continues to use the old digest until someone updates it.
Therefore, digest pinning should always be combined with an update process.
Use Explicit Version Tags Instead of Latest
Another common source of unexpected Docker build behavior is the use of the latest tag.
Consider:
FROM node:latest
The latest tag does not communicate which Node.js release family the application requires.
A future build may use a newer major release with different runtime behavior or compatibility requirements.
A better starting point is an explicit version:
FROM node:22
This is more predictable than latest because it communicates the intended major release.
However, node:22 can still be updated to a newer patch or image build.
For applications that require tighter control, use an explicit patch-level tag and a digest:
FROM node:22.14.0-alpine3.21@sha256:REPLACE_WITH_VERIFIED_DIGEST
The exact tag must exist in the selected registry, and the digest must correspond to that image reference.
Explicit tags make Dockerfiles easier to understand and maintain. Digest pinning provides the stronger guarantee that the build uses the exact referenced image.
Understand Why the --pull Option Matters
Docker can reuse images already available on the local machine.
Suppose a developer has previously pulled an image:
docker pull alpine:3.21
Later, the publisher updates the 3.21 tag.
A normal build may use the locally available image rather than checking whether the tag now points to a newer image.
The --pull option tells Docker to attempt to pull the referenced image before building.
docker build --pull -t my-application .
For Buildx, use:
docker buildx build --pull -t my-application .
This is useful when builds use mutable tags and should check for newer image contents.
However, --pull does not update a digest-pinned reference.
For example:
FROM alpine:3.21@sha256:REPLACE_WITH_VERIFIED_DIGEST
Even when the build uses --pull, Docker retrieves the image identified by the specified digest. It does not replace that digest with the newest image associated with the tag.
This distinction matters when designing CI pipelines.
If you use mutable tags, --pull helps ensure the build checks for updated images.
If you use digest pinning, you need an explicit process to update the digest itself.
Keep Build and Runtime Images Separate
A common Dockerfile mistake is using the same large image for compiling an application and running it in production.
The build environment may contain compilers, SDKs, package managers, and development dependencies that are not required at runtime.
Multi-stage builds allow developers to use different base images for different stages.
Consider an ASP.NET Core application:
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY MyApplication.csproj .
RUN dotnet restore MyApplication.csproj
COPY . .
RUN dotnet publish MyApplication.csproj \
-c Release \
-o /app/publish \
--no-restore
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyApplication.dll"]
The first stage uses the .NET SDK image to restore dependencies and compile the application.
The final stage uses the ASP.NET runtime image, which does not need the complete SDK.
This provides several advantages:
- Smaller production images.
- Fewer unnecessary tools in the runtime environment.
- Reduced attack surface.
- Clear separation between build and runtime dependencies.
However, both base images can change independently.
A production workflow should track and update the SDK and runtime images separately. Pinning only the runtime image while leaving the build image uncontrolled does not make the entire build reproducible.
Also, ensure that the SDK and runtime versions remain compatible with the application being published.
Automate Base Image Updates With Dependabot
Digest pinning provides reproducibility, but manually tracking every base image update can become difficult.
GitHub Dependabot can monitor Docker image dependencies and create pull requests when newer versions are available.
For example, consider this configuration:
version: 2
updates:
- package-ecosystem: "docker"
directory: "/"
schedule:
interval: "weekly"
This configuration tells Dependabot to inspect Docker dependencies in the repository's root directory and check for updates weekly.
If a Dockerfile contains:
FROM alpine:3.21@sha256:OLD_VERIFIED_DIGEST
Dependabot can propose an update when a newer image version or digest is available.
The proposed pull request can then go through the normal CI process.
A useful workflow looks like this:
Base Image Update Available
|
v
Dependabot Creates Pull Request
|
v
Review Updated Image Reference
|
v
Build Docker Image
|
v
Run Unit and Integration Tests
|
v
Scan Image for Vulnerabilities
|
v
Approve and Merge
|
v
Deploy Updated Image
This approach avoids two extremes.
The application does not automatically adopt every upstream image change without validation, and developers do not need to manually check every base image for updates.
For repositories with multiple Dockerfiles, configure the Docker ecosystem for each relevant directory.
Dependabot can also monitor Docker image references in supported deployment manifests.
Validate Base Image Updates Before Merging
An updated base image should be treated like any other dependency update.
A successful Docker build does not guarantee that the application will behave correctly.
For example, an updated base image might include a new system library version. The application may compile successfully but fail at runtime because of a compatibility issue.
A useful validation workflow should include several stages.
Build the updated image
Run the Docker build with the updated base image reference.
docker build --pull \
-t my-application:test .
This confirms that Docker can resolve the image and execute the build instructions.
Run application tests
Start the resulting container and execute the application's test suite.
For example:
docker run --rm \
my-application:test
For applications that expose HTTP endpoints, run integration tests against the container and verify that important application workflows continue to work.
Inspect image vulnerabilities
Use Docker Scout or another container security scanner to inspect the resulting image.
For example:
docker scout quickview my-application:test
A vulnerability scan helps identify known security issues in the image and its dependencies.
An updated base image may resolve existing vulnerabilities, but it can also introduce new packages or expose vulnerabilities that were not present in the previous image.
Compare image behavior
For critical applications, compare the old and new images under the same test conditions.
Check startup time, memory usage, application logs, health checks, and important system dependencies.
This is especially useful when updating images that contain operating system or runtime changes.
Handle Operating System Package Updates Carefully
Pinning a base image does not automatically make every part of a Docker build reproducible.
Consider this Dockerfile:
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y \
curl \
ca-certificates
The base image might be pinned, but apt-get update retrieves package metadata from the configured repositories.
The packages installed by apt-get install can therefore change between builds.
For example, the repository may publish a newer curl package while the Dockerfile remains unchanged.
This means the final image can still differ even though its base image digest is fixed.
A common best practice is to combine apt-get update and apt-get install in the same RUN instruction:
FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends \
curl \
ca-certificates \
&& rm -rf /var/lib/apt/lists/*
Combining the commands prevents Docker from reusing a cached package-index update independently of the installation step.
Removing the package lists also reduces unnecessary data in the resulting layer.
However, this pattern does not pin the exact package versions. If strict reproducibility is required, use an appropriate package versioning or repository snapshot strategy as well.
The same principle applies to other package managers. A pinned base image does not guarantee that dependencies downloaded during subsequent Dockerfile instructions remain unchanged.
Build Multi-Architecture Images Carefully
Many applications need to run on more than one processor architecture.
For example, a team may build images for linux/amd64 and linux/arm64.
A multi-platform image can contain a manifest list or OCI image index that points to different platform-specific images.
This is important when pinning digests.
A digest may identify an image index containing several platform manifests, or it may identify an individual platform-specific image manifest.
For multi-platform builds, teams should understand which digest they are pinning.
Use Docker Buildx to inspect the image:
docker buildx imagetools inspect node:22-alpine
The output displays the available platform manifests.
You can also specify the target platform during a build:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t my-application:latest \
--push .
When using a digest for a multi-platform image, verify that it refers to the intended image index if the same Dockerfile must support multiple architectures.
Using an architecture-specific manifest digest can restrict the build to that platform.
This is particularly important when developers build on Apple Silicon machines but deploy to Linux servers with a different architecture.
Enforce Base Image Standards in CI
For larger organizations, relying on every developer to follow the same Dockerfile practices can become difficult.
Teams can introduce automated checks that enforce approved image sources and digest pinning.
For example, a repository may require:
- Base images from approved registries.
- Explicit image references.
- Digest pinning for production builds.
- Approved operating system and runtime versions.
- Security scanning before deployment.
Docker Buildx supports build policies that can validate build inputs before execution.
Build policies use Rego, a policy language associated with Open Policy Agent.
For example, a policy can require image references to use canonical digest-based identifiers.
Docker's build policy functionality has specific version prerequisites and is an experimental feature in the documented implementation. Organizations should verify the current Buildx and BuildKit requirements before adopting it in production.
For simpler environments, Dockerfile linting and CI scripts can also detect references that use latest or omit a digest.
The important objective is to make the expected image update process consistent across repositories.
A Practical Strategy for Managing Base Image Changes
A reliable approach combines reproducibility with regular security updates.
For development environments, explicit version tags may be sufficient when convenience and frequent updates are priorities.
For production images, digest pinning provides better control over exactly which image contents enter a release.
Automated dependency tools can propose digest updates, while CI validates the new image before it reaches production.
A practical maintenance process should include:
- Use trusted and documented base images.
- Avoid unqualified latest tags.
- Pin production base images to verified digests.
- Track both build-stage and runtime-stage images.
- Automate update pull requests with Dependabot or Renovate.
- Build and test every proposed update.
- Scan images for known vulnerabilities.
- Review package-manager dependencies separately.
- Maintain a record of the image references used in production.
- Remove obsolete digests after the corresponding images are no longer required.
This approach prevents unexpected upstream changes from silently entering production while ensuring that pinned images do not remain outdated indefinitely.
Summary
Docker base image updates are important for security and maintenance, but mutable tags can introduce unexpected changes into otherwise unchanged builds.
A Dockerfile that uses the same tag today and several months later may resolve to different image contents. This can affect operating system packages, system libraries, runtime behavior, and application compatibility.
Digest pinning provides a way to identify an exact image version and make builds more reproducible. However, pinned digests must be updated deliberately to receive security patches.
Tools such as Dependabot and Renovate can automate update proposals, while GitHub Actions can build, test, and scan the updated images before they are merged.
The goal is not to stop Docker base images from changing. It is to make sure every change is visible, reviewed, tested, and introduced into production through a controlled process.
Join the conversation! Your thoughts help the community grow.