Docker Image Layers – What They Are & How They Work

A Docker image layer is a set of filesystem changes applied on top of the previous layer. Individual layers include just the files that a specific Dockerfile instruction added, changed, or removed. Each instruction starts a new layer, although some of these layers may be empty.

For example, the following Dockerfile creates two new layers, one for each of the RUN instructions:

The apk update and apk add nodejs commands are first run as a new layer on top of the last layer in the alpine:latest base image. This layer will include only the new and changed files after Node is installed in the filesystem.

Next, a new file called main.js is created in a second layer. This layer will only include main.js — it will not include the full filesystem from the previous layer. If you modify files that already existed in the previous layer, then the affected files will be copied to the new layer, but others will not.

When you build this image, you’ll see Docker execute the two RUN instructions and export the new image’s layers. The final image is created by assembling the layers into a stack so the topmost layer (main.js) sits on top of the layers below it.

Each layer is essentially a diff of the changes between the current filesystem state and the previous layer. An image is a collection of one or more layers that together define a container’s initial filesystem content.

Docker image layers implement a union filesystem. Each layer includes only the changes its build stage made, but unionization combines an image’s layers to produce a single logical filesystem. This occurs transparently during container runtime.

When you create a container, Docker reads the layers within the image and merges them into a union filesystem for the container to use. No content is copied between layers — the layers are simply overlaid by the union process. 

Docker supports several different unionization systems; overlay2 is the default, but alternatives, including BTRFS, VFS, and ZFS, can be configured instead.

Docker image layers and immutability

Docker image layers are always immutable. Once they’re created, they’re read-only and cannot be modified. Any changes, such as adding or removing files, must be applied in a new layer.

Immutability raises a problem when starting containers. The container may need to write new content to its filesystem, such as temporary files created by the application. 

To solve this issue, Docker adds a transient read-write layer to the top of the union filesystem’s layer stack. This allows the container to write into the filesystem seamlessly, but changes are lost when the container is stopped.

Docker’s layering system makes image operations more efficient and performant. Layers contain just the files that were actually changed by a Dockerfile instruction, so they can be shared between multiple images.

• Efficient reuse – Shared layers between images are cached and not duplicated, reducing storage needs.
• Faster deployments – Unchanged layers are reused, which speeds up builds and reduces push/pull time.
• Incremental updates – Only modified layers are transferred, minimizing bandwidth usage.
• Build consistency – Each layer maps to a specific Dockerfile instruction, making builds reproducible.
• Simplified troubleshooting – The layered structure helps identify which step introduced an issue.
• Modularity and portability – Layers help keep things modular, making images easier to move between environments. The same image runs the same way everywhere.

Sharing layers between images

Here’s a Dockerfile similar to the one shown above. The first RUN instruction hasn’t changed, but the second instruction now writes to a different file:

When you build this image, Docker recognizes that the first layer is already cached on your machine. It was created when the earlier image was built. As a result, the build process for the second image is much quicker because only the second RUN instruction needs to be executed.

The command’s output shows CACHED next to the RUN instruction that installs Node, demonstrating the previously built layer is being reused. The build completes in just 0.9 seconds as a result.

Preventing storage and network resource wastage

The ability to reuse layers significantly reduces storage and bandwidth requirements. For instance, you can adapt the example above to create several images that install Node on top of the alpine base image, but those layers will only need to be stored once on your machine.

Similarly, image registries only need to store the new layers they don’t already have. When users pull an image from a registry, they download only the layers that are missing from their local cache. You can demonstrate this by first pulling an image like node:18:

You can see that Docker had to pull all the layers because none of them had been previously pulled or built. But if you then pull node:20, Docker can reuse the layers that are shared with node:18:

The first four layers have the same IDs (content hashes) as layers also included in the node:18 image. Docker shows Already exists for those layers because they were previously downloaded when pulling node:18.

Debugging builds using intermediate layers

Containers normally start from complete images, but these are simply layers that have been assigned a tag. It’s technically possible to start a container from any layer using its ID (docker run <layer_id>), including intermediate layers produced by Dockerfile build instructions.

Starting a container using an intermediate build layer can be a helpful way to debug build problems. This technique was commonly used in older Docker releases as intermediate layers were preserved by default. 

The IDs associated with each layer were displayed in the build output. Unfortunately, the switch to BuildKit in recent Docker versions prevents the convenient use of intermediate layers because they’re no longer stored after the build completes.

Not every Dockerfile instruction creates a new filesystem layer. Some instructions only add image metadata, which doesn’t affect the image’s filesystem content. These instructions will still add a layer to the stack, but it will be empty and show a size of 0B.

The RUN, COPY, and ADD Docker instructions modify files and create new filesystem layers. All other instructions, including LABEL, CMD, ENTRYPOINT, ENV, and EXPOSE, only set image metadata so they create empty layers.

The docker history command allows you to view all the layers within a particular image:

Here you can see that the layers in our demo image match the instructions from our Dockerfile. The last two layers are inherited from the base image referenced in the Dockerfile’s FROM instruction.

The command displays the ID of each layer, its creation time and size, and the Dockerfile instruction that created it. The IDs of intermediate layers show as <missing> because the image was built using BuildKit. As explained above, BuildKit does not store intermediate image data, but older Docker versions would have kept these layer IDs intact.

You can also inspect the content of image layers using Dive. Dive is a popular open-source community tool for visualizing container images. It provides an interactive terminal interface.

Download and install Dive from its GitHub Releases page. You can then run dive <image> to view the layers in an image:

The interface displays the image’s layers in the top-left. You can switch between layers using the arrow keys. The details of the selected layer are shown below the list, while the file tree on the right lets you inspect the layer’s filesystem.

You can learn more about using Dive in the documentation.

Docker’s image layers and union filesystem make container operations efficient, but there are still steps you can take to keep your builds fast and small. The following three best practices will help you optimize your layer structures to reduce waste.

1. Combine multiple commands as one Dockerfile RUN instruction

Chaining multiple commands into one RUN instruction is frequently more efficient than splitting them across separate instructions. This results in one image layer being created instead of a new layer for each command. As a result, files will only be copied once, even if they’re used by multiple commands.

Try to change the following…

…to this alternative:

A single image layer will now contain all the filesystem changes.

2. Run instructions that rarely need rebuilds first

Efficient use of the Docker build cache depends on Dockerfile instructions appearing before the ones that have frequent changes because they are less likely to need a rebuild., The build cache is invalidated as soon as one layer changes, so all the following layers must then be rebuilt — even if their own content remains the same.

Take the following Dockerfile:

Any changes to the code in the src directory will invalidate the layer cache for the following instructions. This means the npm install instruction will need to be repeated whenever the code changes, wastefully creating new layers. Build time will increase, and more disk space will be used.

You can fix the issue by rearranging the instructions so src is copied after the npm install command. Source code changes will then be layered on top of the npm instruction’s previously cached filesystem.

3. Consider squashing images into a single layer

Images output a stack of layers by default. As we’ve seen in this guide, this enables layers to be reused when building other images or pushing and pulling from registries. But sometimes, squashing your images down to a single layer is preferable.

Squashing can reduce image size, particularly when your build process causes the same file to be written to multiple times. Those files would normally appear in each layer that changes them, even though only the version in the last layer is actually accessible in the image.

The docker build command’s --squash flag can squash images when Docker’s legacy image builder is enabled. At the end of the build, Docker unionizes the contents of all the layers created and stores the resulting filesystem as a single new layer. This layer becomes the final image.

Unfortunately, squashing with the --squash flag has been deprecated and removed from BuildKit. If you’re using BuildKit — the default builder in recent Docker versions — using --squash will display a warning, and your layers will not be squashed:

It’s possible to achieve a similar effect without --squash by writing a multi-stage Dockerfile. In the last stage, you should copy in solely the content from the previous stages that you want your final image to include:

The output image will consist of alpine:latest with the /bin/app path layered on top. The package.json file and the results of npm install and npm build won’t be present in the filesystem, reducing the image’s size.

Best practices for Docker layers focus on improving build speed, reducing image size, and ensuring cache efficiency. Here are the tips to keep in mind when working with Docker image layers:

• Order instructions by volatility – Place frequently changing instructions (e.g., COPY . ., RUN npm install) after static ones to optimize caching.
  
• Minimize layers – Combine related commands using && in a single RUN to reduce image layers without sacrificing readability.
  
• Use multi-stage builds – Compile or build in one stage and copy only the necessary artifacts to the final image to reduce size and avoid exposing sensitive data.
  
• Leverage .dockerignore – Exclude unnecessary files from the build context to avoid invalidating the cache and bloating the image.
  
• Clean up in the same layer – Remove temp files or package managers’ caches within the same RUN command to keep the final layer small.
  
• Use official or minimal base images – Choose slim images (like alpine or debian-slim) unless full-featured ones are necessary.

Docker images consist of layers that are merged into a union filesystem at runtime. Each layer contains just its own filesystem changes relative to the previous layer in the stack. This improves image efficiency as layers can be cached and reused by other builds.

The layering system is designed to be transparent to containers and developers. You don’t need to know exactly how it works to create and use Docker images. However, understanding layers in more depth allows you to optimize your images for faster builds and smaller sizes.

Ready to learn more about Docker images? Check out Spacelift’s guide to writing a Dockerfile or explore how to harden your images in our Docker security best practices post.