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.

Practice

1. What is the main purpose of using COPY --from= in a multi-stage Docker build?

easy

A. To copy files from the host machine to the build stage

B. To copy files from a previous build stage to the final image

C. To copy files from the final image back to the build stage

D. To copy files between two running containers

Solution

1. Step 1: Understand multi-stage builds

   Multi-stage builds allow you to create intermediate stages for building your app.

2. Step 2: Purpose of COPY --from=

   The COPY --from= command copies files from these intermediate stages into the final image, keeping it clean and small.

3. Final Answer:

   To copy files from a previous build stage to the final image -> Option B

4. Quick Check:

   COPY --from= copies from build stage [OK]

Hint: COPY --from= copies from build stage, not host or containers [OK]

Common Mistakes:

• Confusing COPY --from= with copying from host
• Thinking it copies files between containers
• Assuming it copies files back to build stage

2. Which of the following is the correct syntax to copy the file /app/build/output.bin from a build stage named builder to the final image's /app directory?

easy

A. COPY --from=builder /app/build/output.bin /app

B. COPY /app/build/output.bin /app --from=builder

C. COPY builder:/app/build/output.bin /app

D. COPY /app/build/output.bin builder:/app

Solution

1. Step 1: Recall COPY --from= syntax

   The correct syntax is COPY --from=stage source_path destination_path.

2. Step 2: Match the paths and stage name

   COPY --from=builder /app/build/output.bin /app correctly uses --from=builder followed by source and destination paths.

3. Final Answer:

   COPY --from=builder /app/build/output.bin /app -> Option A

4. Quick Check:

   Correct COPY --from= syntax is COPY --from=stage src dst [OK]

Hint: COPY --from= comes before source and destination paths [OK]

Common Mistakes:

• Placing --from= after source and destination
• Using colon syntax like builder:/path (invalid)
• Swapping source and destination paths

3. Given this Dockerfile snippet, what files will be present in the final image's /app directory?

FROM node:18 AS builder
WORKDIR /app
RUN echo "build file" > build.txt

FROM alpine
COPY --from=builder /app/build.txt /app/

medium

A. No /app directory created

B. An empty /app directory

C. The file build.txt with content "build file"

D. The file build.txt but empty

Solution

1. Step 1: Check build stage output

   The builder stage creates /app/build.txt with content "build file".

2. Step 2: COPY from builder to final image

   The final stage copies /app/build.txt from builder to /app/ in the final image.

3. Final Answer:

   The file build.txt with content "build file" -> Option C

4. Quick Check:

   File copied with content preserved [OK]

Hint: COPY --from= copies actual files, not empty placeholders [OK]

Common Mistakes:

• Assuming directory is empty after copy
• Thinking file content is lost
• Assuming /app directory is missing

4. Identify the error in this Dockerfile snippet that tries to copy from a build stage named builder:

FROM golang:1.20 AS builder
WORKDIR /app
RUN go build -o myapp

FROM alpine
COPY /app/myapp --from=builder /usr/local/bin/myapp

medium

A. The --from=builder flag is placed after the source path

B. The build stage name builder is missing

C. The destination path /usr/local/bin/myapp is invalid

D. The RUN go build command is incorrect

Solution

1. Step 1: Check COPY command syntax

   The correct syntax is COPY --from=builder source destination. The flag must come before paths.

2. Step 2: Identify error in given command

   The command places --from=builder after the source path, which is invalid syntax.

3. Final Answer:

   The --from=builder flag is placed after the source path -> Option A

4. Quick Check:

   --from= must come before source path [OK]

Hint: Place --from= before source path in COPY command [OK]

Common Mistakes:

• Putting --from= after source path
• Forgetting to name the build stage
• Assuming destination path is invalid without checking

5. You want to build a Docker image for a Python app. The build stage installs dependencies and creates a dist/app.tar.gz file. The final stage should only copy this archive and extract it to /app. Which Dockerfile snippet correctly copies and extracts the archive from the build stage named builder?

hard

A. FROM python:3.12 AS builder\nWORKDIR /src\nRUN pip install -r requirements.txt\nRUN tar czf dist/app.tar.gz .\n\nFROM python:3.12-slim\nWORKDIR /app\nCOPY --from=builder /src/dist/app.tar.gz /app/\nRUN tar xzf /app/app.tar.gz

B. FROM python:3.12 AS builder\nWORKDIR /src\nRUN pip install -r requirements.txt\nRUN tar czf dist/app.tar.gz .\n\nFROM python:3.12-slim\nWORKDIR /app\nCOPY /src/dist/app.tar.gz --from=builder ./\nRUN tar xzf app.tar.gz

C. FROM python:3.12 AS builder\nWORKDIR /src\nRUN pip install -r requirements.txt\nRUN tar czf dist/app.tar.gz .\n\nFROM python:3.12-slim\nWORKDIR /app\nCOPY --from=builder /dist/app.tar.gz ./\nRUN tar xzf app.tar.gz

D. FROM python:3.12 AS builder\nWORKDIR /src\nRUN pip install -r requirements.txt\nRUN tar czf dist/app.tar.gz .\n\nFROM python:3.12-slim\nWORKDIR /app\nCOPY --from=builder /src/dist/app.tar.gz ./\nRUN tar xzf app.tar.gz

Solution

1. Step 1: Verify COPY --from= syntax and source path

   The builder stage (WORKDIR /src) creates dist/app.tar.gz at /src/dist/app.tar.gz. Correctly uses COPY --from=builder /src/dist/app.tar.gz ./ with --from=builder first and absolute source path.

2. Step 2: Confirm extraction command and paths

   Final stage WORKDIR /app, copy to ./ places app.tar.gz there. RUN tar xzf app.tar.gz extracts correctly.

3. Final Answer:

   COPY --from=builder /src/dist/app.tar.gz ./\nRUN tar xzf app.tar.gz -> Option D

4. Quick Check:

   COPY --from= before source path, extract in correct directory [OK]

Hint: COPY --from= before source path; extract where file copied [OK]

Common Mistakes:

• Placing --from= after source path
• Using wrong source path like /dist/app.tar.gz instead of /src/dist/app.tar.gz
• Extracting archive from wrong directory