To appreciate layers, first imagine life without them.

Suppose that every Docker image were one single, giant file. You build an application, and Docker packs the operating system files, the programming language, your libraries, and your own code into one huge block. Now imagine you have fifty applications, and forty of them use the same operating system files and the same language runtime. With a single-block design, you would store the same operating system fifty times. Every download would repeat the same gigabytes. Every tiny code change would force a brand-new giant block to be built and shipped.

That would be wasteful and slow. Developers change their own code many times a day, but the operating system underneath changes rarely. It makes no sense to rebuild and resend the rarely changing parts each time. Docker solves this by cutting an image into layers, where each layer holds only one small set of changes. Layers that stay the same are reused. Only the layers that changed need to be rebuilt or sent.

This one design decision is behind many of Docker’s best qualities: fast builds, quick downloads, small storage use, and the ability for hundreds of containers to share the same base. When you understand layers, you understand why Docker feels so fast compared with older ways of packaging software.

A small glossary will make the rest of this guide easy to read.

A layer is a recorded set of changes to the file system, packed into a single unit.

An image layer is a snapshot of the differences made to the files of an image at one step of its construction. It does not contain a complete copy of everything. It contains only what changed compared with the layer below it. Perhaps a layer adds a set of new programs. Perhaps another adds your application files. Perhaps a third changes a single settings file. Each of these is stored as its own layer.

Behind the scenes, a layer is stored as a compressed archive of files, together with a fingerprint that identifies it. Once a layer is created, it is never edited. It is read-only and permanent. If something needs to change, Docker does not go back and alter the old layer. It creates a new layer on top that records the change. This keeps every layer trustworthy and reusable.

Layers Are About Differences

The idea of storing only differences is the secret to saving space. Think about a document with ten versions. You could keep ten full copies, or you could keep one original and a note for each version saying what was changed. The second approach uses far less space. Layers work like those notes. The bottom layer holds a base set of files, and each layer above it records what was added, changed, or removed.

An image is more than a pile of layers. It has a few small companion pieces.

When Docker stores or ships an image, it treats it as a small collection of parts. Understanding these parts explains how Docker knows which layers belong to which image and in what order to stack them.

graph TD
  T["Tag: friendly name"] --> M["Manifest: table of contents"]
  M --> C["Configuration: settings and layer order"]
  M --> L1["Layer 1: base system files"]
  M --> L2["Layer 2: language runtime"]
  M --> L3["Layer 3: application libraries"]
  M --> L4["Layer 4: your application code"]
        

Notice that the tag sits at the very top. A tag is only a label stuck onto a manifest. The same image can carry several tags, and a tag can be moved from one image to another. The layers and the fingerprints below it are the true, unchanging identity of the image.

Layers are not created randomly. They come directly from the steps of your build recipe.

A Dockerfile is a list of instructions read from top to bottom. Some of these instructions change the files inside the image, and those create a real layer. Other instructions only record information, such as which command should run when a container starts, and those add a small piece of settings without adding meaningful file content.

Instructions That Add Real Layers

Instructions That Only Record Settings

Instructions that set an environment value, choose a working folder, declare a port, add a label, or define the default start command mostly record metadata. They are stored in the image configuration, and they take up essentially no space. They matter for how the container behaves, but they do not add files to the stack.

flowchart TD
  A["Base image layers"] --> B["Step: install software"]
  B --> C["New layer: installed files"]
  C --> D["Step: copy application files"]
  D --> E["New layer: application code"]
  E --> F["Step: set start command"]
  F --> G["Settings only, no new files"]
  G --> H["Finished image"]
        

Stacked layers must be shown to a container as one ordinary, complete file system. A clever technology makes this possible.

When a container starts, it must see a single normal set of folders and files, as if nothing were layered at all. The tool that creates this illusion is called a union file system. Its job is to take many separate layers and present them as one merged view. On modern Linux systems, Docker normally uses a storage driver named overlay2, which is built on a kernel feature for exactly this purpose.

The rules of the merged view are simple. When the container looks for a file, the system searches from the top layer down to the bottom. The first layer that contains that file wins, and the container sees that version. Lower layers that also contain the same file are hidden beneath it. If a higher layer marks a file as removed, the file appears deleted, even though it still exists in a lower layer.

graph TD
  W["Container writable layer: temporary changes"] --> A["Image layer 4: application code"]
  A --> B["Image layer 3: libraries"]
  B --> C["Image layer 2: runtime"]
  C --> D["Image layer 1: base system"]
  W -.-> V["Merged view seen by the container"]
  A -.-> V
  B -.-> V
  C -.-> V
  D -.-> V
        

The Three Folders Behind the Scenes

Under the hood, overlay2 uses three ideas. The lower folders hold the read-only image layers. The upper folder is the writable layer that belongs to the specific container. The merged folder is the combined view that the container actually sees. You rarely touch these directly, but knowing they exist makes the whole system feel much less mysterious.

Image layers are read-only, so where do a running container’s changes go?

When Docker starts a container from an image, it adds one extra layer on top of the stack. This layer is thin, empty at first, and writable. Anything the running application creates, changes, or deletes is recorded in this top layer. The image layers below are never touched. This is what lets a hundred containers share the same image without interfering with one another: each gets its own private writable layer on top of the same shared base.

What Is Copy-on-Write?

Sometimes a container needs to modify a file that lives in a lower, read-only layer. The system cannot edit the file in place, because that layer is shared. Instead, it uses a strategy called copy-on-write. The first time the container tries to change the file, the system quietly copies that file up into the container’s writable layer, and the change is applied to the copy. From then on, the container sees the modified copy, and the original in the lower layer remains untouched for everyone else.

sequenceDiagram
  participant App as Application in container
  participant W as Writable layer
  participant L as Read-only image layers
  App->>W: Ask to modify a file
  W->>L: Is the file here?
  L-->>W: Yes, found in a lower layer
  W->>W: Copy the file up into the writable layer
  W-->>App: Change applied to the copy
        

Because copy-on-write copies whole files, writing heavily to large files inside a container’s writable layer can be slow. This is another reason why volumes are recommended for data-heavy work: they bypass the layered system and talk to the disk more directly.

Every layer has a unique identity based on what it contains, not on what someone decided to call it.

Docker identifies each layer by a digest, which is a long fingerprint calculated from the layer’s contents using a strong mathematical method. The idea is simple. If two layers contain exactly the same files, they produce exactly the same fingerprint. If even a single byte differs, the fingerprint is completely different.

This approach is called content-addressable storage, meaning that content is found by what it is rather than by a name. It has powerful consequences. Because identical content has an identical fingerprint, Docker can recognize that two images use the same layer, and store that layer only once on disk. It can also verify that a downloaded layer has not been damaged or tampered with, simply by recalculating the fingerprint and comparing.

Layers make downloading and uploading images remarkably efficient.

When you ask Docker to download an image, it first fetches the manifest, which lists all the layer fingerprints. Then, for each layer, Docker checks whether that fingerprint already exists on your machine. If it does, the layer is skipped. Only the missing layers are downloaded, and they can be downloaded at the same time to save time. This is why the second image you pull from the same family is usually much faster than the first.

Uploading works the same way in reverse. When you send an image to a registry, Docker asks the registry which layers it already holds. Only the layers the registry lacks are uploaded. If you have changed only the top layer that contains your application code, only that small layer travels across the network, even though the image as a whole may be hundreds of megabytes.

sequenceDiagram
  participant M as Your machine
  participant R as Registry
  M->>R: Request image manifest
  R-->>M: List of layer fingerprints
  M->>M: Compare with layers already stored
  M->>R: Request only the missing layers
  R-->>M: Send missing layers
  M->>M: Verify fingerprints and assemble the image
        

Layers are the reason a second build can finish in seconds instead of minutes.

When Docker builds an image, it remembers every layer it has produced. On the next build, it walks through your recipe from the top. For each step, it asks a simple question: “Is this exactly the same step as last time, sitting on top of exactly the same layers, with exactly the same input files?” If the answer is yes, Docker reuses the stored layer and skips the work. This is called a cache hit.

The moment Docker meets a step that differs from before, it must build that step again. And here is the crucial rule: once one step is rebuilt, every step after it must also be rebuilt, because each later layer sits on top of the changed one. The cache is valid only as a continuous chain from the top of the recipe down to the first change.

flowchart TD
  A["Step 1: base image"] --> B{"Same as last build?"}
  B -- Yes --> C["Reuse cached layer"]
  B -- No --> X["Rebuild this and every later step"]
  C --> D["Step 2: install dependencies"]
  D --> E{"Same as last build?"}
  E -- Yes --> F["Reuse cached layer"]
  E -- No --> X
  F --> G["Step 3: copy application code"]
  G --> H{"Files changed?"}
  H -- Yes --> Y["Rebuild only this and later steps"]
  H -- No --> Z["Reuse cached layer"]
        

The Golden Rule of Ordering

Because a change invalidates everything after it, the order of your steps matters enormously. Steps that rarely change, such as installing the operating-system tools and the project’s dependencies, should come first. Steps that change often, such as copying your own application code, should come last. That way, an everyday code change invalidates only the final layer, and the expensive earlier layers are reused from the cache.

One of the most surprising facts about layers is that removing a file in a later layer does not make the image smaller.

Because layers are read-only and permanent, a later layer cannot truly erase something that an earlier layer already contains. When a later step deletes a file, Docker records a special marker, sometimes called a whiteout, in the new layer. This marker tells the merged view to hide the file. The file disappears from what the container sees, but its bytes still sit inside the lower layer, and they are still downloaded, stored, and shipped with the image.

Imagine a step that downloads a large installer, another step that uses it to install a program, and a third step that deletes the installer. The final image looks clean, yet the layer that first added the installer still carries all its bytes. The image is just as large as if the deletion never happened. Many beginners are baffled when a cleanup step fails to shrink the image.

A handful of simple techniques keep images lean and builds fast.

Multi-Stage Builds in Plain Words

A multi-stage build is like cooking in a messy workshop and then serving in a clean dining room. In the first stage, you use a large image with compilers and build tools to produce your finished application. In the final stage, you start from a tiny clean image and copy in only the finished product. None of the workshop clutter, meaning the compilers, temporary files, and source code, ever makes it into the shipped layers.

flowchart LR
  A["Stage 1: large build image with heavy tools"] --> B["Compile and produce the finished application"]
  B --> C["Copy only the result"]
  C --> D["Stage 2: small clean runtime image"]
  D --> E["Final image: lean and secure"]
        

Because layers are permanent, whatever goes into them stays there.

The permanence of layers has an important security consequence. If a password, a key, or any secret ever enters a layer, it remains in that layer forever, even if a later step deletes it. Anyone who can download the image can unpack its layers one by one and read the secret. Deleting it in a later layer only hides it from the final merged view, not from the layer archive itself.

Other Security Points

The fingerprint system helps here too. Because each layer’s digest is derived from its content, you can verify that the layers you run are exactly the ones that were tested and scanned. Any silent tampering would change the fingerprint and be detected.

You can see the layers of an image and watch how much disk they use.

Docker provides tools to look at how an image was constructed. A history view lists every step that contributed to an image, in order, along with the size each step added. This is the fastest way to discover which step is responsible for a bloated image. You will often spot a single step that added hundreds of megabytes, and that tells you exactly where to focus your effort.

An inspection view shows the image’s configuration and the list of layer fingerprints. Community tools also exist that let you browse each layer’s file changes visually, showing what was added, modified, or removed at every step. These are excellent for learning and for hunting wasted space.

Watching Disk Usage

Layers accumulate quietly. Every image you pull, every build you run, and every intermediate result adds to disk usage. Docker has a summary view that reports how much space is used by images, containers, volumes, and build cache, and how much of it could be reclaimed. Dangling layers, which are layers no longer referenced by any tagged image, are a common source of wasted space after many rebuilds.

The layered design brings big benefits and a few costs worth knowing about.

A table to keep layers, images, containers, and volumes clearly separate in your mind.

Layers Versus a Virtual Machine Disk

A traditional virtual machine stores its entire operating system on a single, fully writable virtual disk. Ten identical virtual machines usually mean ten full copies of the disk. Docker layers avoid that duplication by sharing the read-only parts and keeping only tiny writable layers per container. That difference is one of the main reasons containers are so much lighter than virtual machines.

Layers quietly power many everyday situations.

Habits that make images lean, and habits that quietly bloat them.

Helpful Patterns

Anti-Patterns to Avoid

A short list to keep your layers small, fast, and safe.

An image layer is a read-only record of the file changes made at one step of building an image, and Docker stacks many of these to form the complete image.

No. Steps that change files, such as running a command or copying files, create real layers. Steps that only record settings, such as environment values or the default start command, add metadata but essentially no file content.

Because the files still exist inside the earlier layer that added them. A later deletion only hides them in the merged view. Clean up within the same step that created the files, or use a multi-stage build.

Yes, and this is one of Docker’s biggest strengths. Layers with identical content have identical fingerprints and are stored only once on disk, no matter how many images use them.

Into a thin writable layer that sits on top of the image layers. It belongs only to that container and is deleted when the container is removed.

Often because an early step changes on each build and invalidates the cache for every step after it. Reorder your recipe so stable steps come first and frequently changing files are copied last.

Not always. Grouping related steps can reduce waste, but merging everything into one step ruins cache reuse. Aim for a balanced, sensible grouping rather than the smallest possible number.

No. The secret stays inside the earlier layer and can be extracted by anyone with access to the image. Never place secrets in an image at all.

In the Docker daemon’s data folder, which on Linux is by default under the location /var/lib/docker. Manage them through Docker’s own tools rather than editing that folder by hand.

A layer is read-only content that is part of an image, or a temporary writable layer that dies with the container. A volume is a separate storage area that survives container removal and is meant for data you want to keep.

A Docker image is not one solid block. It is a neat stack of read-only layers, each recording a small set of file changes made by one step of the build. A union file system merges the layers into one clean view, and a thin writable layer on top lets each running container make its own private changes through copy-on-write. Fingerprints identify layers by their content, which lets Docker store shared layers only once, verify their integrity, and move only the missing pieces across the network. The build cache reuses unchanged layers to make repeat builds fast, but only when steps are ordered wisely. Because layers are permanent, deleted files still cost space and secrets never truly disappear. By choosing small bases, ordering steps carefully, cleaning up in the same step, and using multi-stage builds, you turn layers from a mystery into a powerful ally.