docker build (legacy builder)

Description

Note

This page refers to the legacy implementation of docker build, using the legacy (pre-BuildKit) build backend. This configuration is only relevant if you're building Windows containers.

For information about the default docker build, using Buildx, see docker buildx build.

When building with legacy builder, images are created from a Dockerfile by running a sequence of commits. This process is inefficient and slow compared to using BuildKit, which is why this build strategy is deprecated for all use cases except for building Windows containers. It's still useful for building Windows containers because BuildKit doesn't yet have full feature parity for Windows.

Builds invoked with docker build use Buildx (and BuildKit) by default, unless:

• You're running Docker Engine in Windows container mode
• You explicitly opt out of using BuildKit by setting the environment variable DOCKER_BUILDKIT=0.

The descriptions on this page only covers information that's exclusive to the legacy builder, and cases where behavior in the legacy builder deviates from behavior in BuildKit. For information about features and flags that are common between the legacy builder and BuildKit, such as --tag and --target, refer to the documentation for docker buildx build.

Build context with the legacy builder

The build context is the positional argument you pass when invoking the build command. In the following example, the context is ., meaning current the working directory.

$ docker build .

When using the legacy builder, the build context is sent over to the daemon in its entirety. With BuildKit, only the files you use in your builds are transmitted. The legacy builder doesn't calculate which files it needs beforehand. This means that for builds with a large context, context transfer can take a long time, even if you're only using a subset of the files included in the context.

When using the legacy builder, it's therefore extra important that you carefully consider what files you include in the context you specify. Use a .dockerignore file to exclude files and directories that you don't require in your build from being sent as part of the build context.

Accessing paths outside the build context

The legacy builder will error out if you try to access files outside of the build context using relative paths in your Dockerfile.

FROM alpine
COPY ../../some-dir .

$ docker build .
...
Step 2/2 : COPY ../../some-dir .
COPY failed: forbidden path outside the build context: ../../some-dir ()

BuildKit on the other hand strips leading relative paths that traverse outside of the build context. Re-using the previous example, the path COPY ../../some-dir . evaluates to COPY some-dir . with BuildKit.

Options

Examples

Specify isolation technology for container (--isolation)

This option is useful in situations where you are running Docker containers on Windows. The --isolation=<value> option sets a container's isolation technology. On Linux, the only supported is the default option which uses Linux namespaces. On Microsoft Windows, you can specify these values:

Specifying the --isolation flag without a value is the same as setting --isolation="default".

Optional security options (--security-opt)

This flag is only supported on a daemon running on Windows, and only supports the credentialspec option. The credentialspec must be in the format file://spec.txt or registry://keyname.

Squash an image's layers (--squash) (experimental)

Overview

Note

The --squash option is an experimental feature, and should not be considered stable.

Once the image is built, this flag squashes the new layers into a new image with a single new layer. Squashing doesn't destroy any existing image, rather it creates a new image with the content of the squashed layers. This effectively makes it look like all Dockerfile commands were created with a single layer. The --squash flag preserves the build cache.

Squashing layers can be beneficial if your Dockerfile produces multiple layers modifying the same files. For example, files created in one step and removed in another step. For other use-cases, squashing images may actually have a negative impact on performance. When pulling an image consisting of multiple layers, the daemon can pull layers in parallel and allows sharing layers between images (saving space).

For most use cases, multi-stage builds are a better alternative, as they give more fine-grained control over your build, and can take advantage of future optimizations in the builder. Refer to the Multi-stage builds section for more information.

Known limitations

The --squash option has a number of known limitations:

• When squashing layers, the resulting image can't take advantage of layer sharing with other images, and may use significantly more space. Sharing the base image is still supported.
• When using this option you may see significantly more space used due to storing two copies of the image, one for the build cache with all the cache layers intact, and one for the squashed version.
• While squashing layers may produce smaller images, it may have a negative impact on performance, as a single layer takes longer to extract, and you can't parallelize downloading a single layer.
• When attempting to squash an image that doesn't make changes to the filesystem (for example, the Dockerfile only contains ENV instructions), the squash step will fail (see issue #33823).

Prerequisites

The example on this page is using experimental mode in Docker 23.03.

You can enable experimental mode by using the --experimental flag when starting the Docker daemon or setting experimental: true in the daemon.json configuration file.

By default, experimental mode is disabled. To see the current configuration of the Docker daemon, use the docker version command and check the Experimental line in the Engine section:

Client: Docker Engine - Community
 Version:           23.0.3
 API version:       1.42
 Go version:        go1.19.7
 Git commit:        3e7cbfd
 Built:             Tue Apr  4 22:05:41 2023
 OS/Arch:           darwin/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          23.0.3
  API version:      1.42 (minimum version 1.12)
  Go version:       go1.19.7
  Git commit:       59118bf
  Built:            Tue Apr  4 22:05:41 2023
  OS/Arch:          linux/amd64
  Experimental:     true
 [...]

Build an image with the --squash flag

The following is an example of a build with the --squash flag. Below is the Dockerfile:

FROM busybox
RUN echo hello > /hello
RUN echo world >> /hello
RUN touch remove_me /remove_me
ENV HELLO=world
RUN rm /remove_me

Next, build an image named test using the --squash flag.

$ docker build --squash -t test .

After the build completes, the history looks like the below. The history could show that a layer's name is <missing>, and there is a new layer with COMMENT merge.

$ docker history test

IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
4e10cb5b4cac        3 seconds ago                                                       12 B                merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702 to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb
<missing>           5 minutes ago       /bin/sh -c rm /remove_me                        0 B
<missing>           5 minutes ago       /bin/sh -c #(nop) ENV HELLO=world               0 B
<missing>           5 minutes ago       /bin/sh -c touch remove_me /remove_me           0 B
<missing>           5 minutes ago       /bin/sh -c echo world >> /hello                 0 B
<missing>           6 minutes ago       /bin/sh -c echo hello > /hello                  0 B
<missing>           7 weeks ago         /bin/sh -c #(nop) CMD ["sh"]                    0 B
<missing>           7 weeks ago         /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff   1.113 MB

Test the image, check for /remove_me being gone, make sure hello\nworld is in /hello, make sure the HELLO environment variable's value is world.