Copying from build stage to final stage in Docker - Deep Dive

Overview - Copying from build stage to final stage

What is it?

Copying from build stage to final stage is a technique in Docker where you create multiple steps in a Dockerfile. You first build your application or dependencies in one stage, then copy only the needed files to a smaller final stage. This helps keep the final image small and secure by excluding unnecessary build tools and files.

Why it matters

Without this technique, Docker images become large and bloated because they include all build tools and temporary files. This slows down deployment, wastes storage, and increases security risks. Copying from build to final stage solves these problems by producing lean images that run faster and are easier to manage.

Where it fits

Before learning this, you should understand basic Dockerfile commands like RUN, COPY, and how Docker images are built. After mastering this, you can explore multi-stage builds in more depth and advanced image optimization techniques.

Mental Model

Core Idea

Multi-stage Docker builds let you separate building your app from packaging it, copying only what’s needed into the final image.

Think of it like...

It's like cooking a meal in one kitchen and then only packing the finished dish into a lunchbox, leaving all the dirty pots and ingredients behind.

┌───────────────┐       ┌───────────────┐
│ Build Stage   │       │ Final Stage   │
│ (build tools) │       │ (runtime only)│
│ ┌───────────┐ │       │               │
│ │ Compile   │ │──────▶│ COPY needed   │
│ │ & build   │ │       │ files only    │
│ └───────────┘ │       │               │
└───────────────┘       └───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding Dockerfile stages

Concept: Dockerfiles can have multiple stages, each starting with a FROM instruction.

A Dockerfile usually starts with FROM to specify a base image. You can have multiple FROM lines, each creating a new stage. Each stage can run commands independently.

Result

You can build images with multiple stages, but by default, only the last stage is kept as the final image.

Knowing that each FROM starts a new stage is key to understanding how multi-stage builds work.

2

Foundation

Basic COPY command usage

Concept: COPY copies files from your build context into the image filesystem.

COPY copies files or folders from your local machine (build context) into the image at build time.

Result

Files appear inside the image at the specified destination path.

COPY is the main way to get your app code or artifacts into the image.

3

Intermediate

Introducing multi-stage build syntax

🤔Before reading on: do you think you can copy files from one stage to another directly? Commit to yes or no.

Concept: You can name build stages and copy files between them using stage names.

Use FROM AS to name a stage. Later stages can COPY --from= to copy files from previous stages.

Result

Files built or created in one stage can be selectively copied into another stage.

Understanding stage naming and --from lets you separate build and runtime environments cleanly.

4

Intermediate

Selective copying for smaller images

🤔Before reading on: do you think copying the entire build directory is better or copying only needed files? Commit to your answer.

Concept: Copying only necessary files from build stage reduces final image size and attack surface.

Instead of copying the whole build directory, specify only the files or folders your app needs to run, like binaries or config files.

Result

Final image is smaller, faster to deploy, and more secure.

Knowing what your app actually needs at runtime helps optimize images effectively.

5

Advanced

Using multi-stage builds for dependency management

🤔Before reading on: do you think build tools must be present in the final image? Commit to yes or no.

Concept: Build tools and dependencies can stay in build stages and be excluded from the final image.

Install compilers, package managers, and other heavy tools only in build stages. Copy only the compiled app or runtime dependencies to the final stage.

Result

Final image contains only runtime essentials, improving security and performance.

Separating build and runtime environments prevents unnecessary tools from increasing image size or attack surface.

6

Expert

Advanced tricks with multi-stage copying

🤔Before reading on: can you copy files from multiple build stages into one final stage? Commit to yes or no.

Concept: You can copy from multiple stages and use complex patterns to optimize final images.

Use multiple COPY --from=stage commands to gather artifacts from different build stages. Combine this with caching and conditional builds for efficient pipelines.

Result

Highly optimized images tailored to production needs with minimal size and maximum speed.

Mastering multi-stage copying unlocks powerful image optimization and build pipeline flexibility.

Under the Hood

Docker builds each stage as a separate temporary image layer. When you use COPY --from=stage, Docker extracts files from the specified stage's image layers and adds them to the current stage. Only the final stage's image is saved as the output. Intermediate stages are discarded unless explicitly tagged.

Why designed this way?

This design allows developers to separate concerns: build complexity and runtime simplicity. It avoids shipping build tools and temporary files in production images, reducing size and security risks. Earlier Docker versions lacked this, leading to bloated images.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Stage 1       │       │ Stage 2       │       │ Final Stage   │
│ (build tools) │       │ (compile)     │       │ (runtime)     │
│ ┌───────────┐ │       │ ┌───────────┐ │       │               │
│ │ Build app │ │──────▶│ │ Copy app  │ │──────▶│ COPY --from=1 │
│ └───────────┘ │       │ └───────────┘ │       │ only needed   │
└───────────────┘       └───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does COPY --from copy files at runtime or build time? Commit to your answer.

Common Belief: COPY --from copies files when the container runs, so files can change dynamically.

Reality: COPY --from copies files only during image build time, making the final image static.

Why it matters: Thinking files copy at runtime leads to confusion about image immutability and debugging failures.

Quick: Can you copy files from a stage that comes after the current one? Commit yes or no.

Common Belief: You can copy files from any stage regardless of order in the Dockerfile.

Reality: You can only copy from stages defined before the current stage in the Dockerfile.

Why it matters: Trying to copy from a later stage causes build errors and wasted debugging time.

Quick: Does copying the entire build directory always produce the smallest image? Commit yes or no.

Common Belief: Copying the whole build directory is simpler and always better.

Reality: Copying everything bloats the image with unnecessary files, increasing size and attack surface.

Why it matters: Ignoring selective copying leads to inefficient images that slow deployment and increase security risks.

Quick: Is multi-stage build only for reducing image size? Commit yes or no.

Common Belief: Multi-stage builds exist only to make images smaller.

Reality: They also improve security, separate build/runtime concerns, and enable complex build pipelines.

Why it matters: Underestimating multi-stage builds limits their use to size reduction, missing broader benefits.

Expert Zone

1

Copying files preserves file metadata like permissions and timestamps, which can affect runtime behavior.

2

Using named stages allows caching and reuse in complex CI/CD pipelines, speeding up builds.

3

You can combine multi-stage builds with build arguments and conditional logic for dynamic image creation.

When NOT to use

Avoid multi-stage builds when your application is extremely simple or when build time overhead outweighs image size benefits. Alternatives include single-stage builds or using external build tools to prepare artifacts before Docker build.

Production Patterns

In production, multi-stage builds are used to compile code in one stage, run tests in another, and package only the final binaries and configs in the last stage. This pattern ensures minimal, secure images deployed to production.

Connections

Continuous Integration Pipelines

Multi-stage builds integrate with CI pipelines to optimize build speed and artifact management.

Understanding multi-stage builds helps design efficient CI workflows that produce lean deployable images.

Software Build Systems

Multi-stage Docker builds mirror traditional build systems separating compile and package steps.

Knowing build systems clarifies why separating build and runtime stages improves maintainability and security.

Lean Manufacturing

Both focus on eliminating waste by only keeping what is necessary in the final product.

Recognizing this connection highlights the universal value of minimalism and efficiency in processes.

Common Pitfalls

#1 Copying entire build directory bloats image size.

Wrong approach:

COPY --from=builder /app /app

Correct approach:

COPY --from=builder /app/dist/myapp /app/myapp

Root cause:

Not understanding which files are needed at runtime leads to copying unnecessary build artifacts.

#2 Trying to copy from a stage defined after the current stage.

Wrong approach:

COPY --from=final /app /app

Correct approach:

COPY --from=builder /app /app

Root cause:

Misunderstanding Dockerfile stage order causes build failures.

#3 Including build tools in the final image.

Wrong approach:

FROM build-image
RUN apt-get install build-tools
COPY . /app
CMD run-app

Correct approach:

FROM build-image AS builder
RUN apt-get install build-tools
COPY . /app
RUN build-app
FROM runtime-image
COPY --from=builder /app/dist /app
CMD run-app

Root cause:

Not separating build and runtime stages leads to large, insecure images.

Key Takeaways

Multi-stage Docker builds let you separate building your app from packaging it, keeping final images small and secure.

You can name build stages and copy files selectively from earlier stages using COPY --from.

Copying only necessary files reduces image size, speeds deployment, and lowers security risks.

Build tools and temporary files should stay in build stages, never in the final runtime image.

Mastering multi-stage copying unlocks powerful optimization and flexible build pipelines.