Squashing layers in Docker - Commands & Configuration

Introduction

When you build a Docker image, each command creates a new layer. Squashing layers means combining these layers into fewer layers to make the image smaller and simpler.

When you want to reduce the size of your Docker image to save disk space and speed up downloads.

When you want to hide intermediate build steps and keep your image clean.

When you have many small layers from multiple RUN commands and want to combine them.

When you want to improve caching efficiency by reducing the number of layers.

When you want to optimize images for production deployment.

Config File - Dockerfile

Dockerfile

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
RUN curl -o /tmp/sample.txt https://example.com/sample.txt
RUN echo "Hello World" > /tmp/hello.txt
CMD ["cat", "/tmp/hello.txt"]

This Dockerfile starts from an Ubuntu base image.

It updates package lists and installs curl in one layer.

Then it downloads a sample file in another layer.

It creates a text file in a third layer.

The CMD runs a command to show the hello.txt content.

Commands

This command builds the Docker image from the Dockerfile in the current folder and squashes all layers into one to reduce image size.

Terminal

docker build --squash -t my-squashed-image .

Expected Output

[+] Building 10.2s (8/8) FINISHED

 => [internal] load build definition from Dockerfile

 => => transferring dockerfile: 123B

 => [internal] load .dockerignore

 => => transferring context: 2B

 => [internal] load metadata for docker.io/library/ubuntu:22.04

 => [1/4] FROM docker.io/library/ubuntu:22.04

 => CACHED

 => [2/4] RUN apt-get update && apt-get install -y curl

 => [3/4] RUN curl -o /tmp/sample.txt https://example.com/sample.txt

 => [4/4] RUN echo "Hello World" > /tmp/hello.txt

 => exporting to image

 => => exporting layers

 => => writing image sha256:abc123def4567890

 => => naming to docker.io/library/my-squashed-image

→

--squash - Combines all layers into one during build to reduce image size.

→

-t - Tags the image with a name for easy reference.

This command lists the image details to verify the image was created and check its size.

Terminal

docker images my-squashed-image

Expected Output

REPOSITORY          TAG       IMAGE ID       CREATED          SIZE

my-squashed-image   latest    abc123def456   10 seconds ago   75MB

Runs the image to check that the final command works and the image behaves as expected.

Terminal

docker run --rm my-squashed-image

Expected Output

Hello World

→

--rm - Automatically removes the container after it exits.

Key Concept

If you remember nothing else from this pattern, remember: squashing combines multiple image layers into one to make Docker images smaller and cleaner.

Common Mistakes

Trying to use --squash without enabling experimental features in Docker.

The --squash flag requires Docker's experimental mode to be enabled, otherwise the build will fail.

Enable experimental features by adding {"experimental": "enabled"} to the Docker CLI config file or use Docker BuildKit which supports squashing.

Using multiple RUN commands without squashing and expecting a small image.

Each RUN command creates a new layer, so the image size grows with each command.

Combine commands in a single RUN or use --squash to merge layers.

Summary

Use the --squash flag with docker build to combine image layers into one.

Squashing reduces image size and hides intermediate build steps.

Verify the image size and functionality by listing images and running the container.