docker build (legacy builder)
Description | Build an image from a Dockerfile |
---|---|
Usage | docker image build [OPTIONS] PATH | URL | - |
Aliases | docker image build
docker build
docker builder build |
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, seedocker 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
Option | Default | Description |
---|---|---|
--add-host | Add a custom host-to-IP mapping (host:ip ) | |
--build-arg | Set build-time variables | |
--cache-from | Images to consider as cache sources | |
--cgroup-parent | Set the parent cgroup for the RUN instructions during build | |
--compress | Compress the build context using gzip | |
--cpu-period | Limit the CPU CFS (Completely Fair Scheduler) period | |
--cpu-quota | Limit the CPU CFS (Completely Fair Scheduler) quota | |
-c, --cpu-shares | CPU shares (relative weight) | |
--cpuset-cpus | CPUs in which to allow execution (0-3, 0,1) | |
--cpuset-mems | MEMs in which to allow execution (0-3, 0,1) | |
--disable-content-trust | true | Skip image verification |
-f, --file | Name of the Dockerfile (Default is PATH/Dockerfile ) | |
--force-rm | Always remove intermediate containers | |
--iidfile | Write the image ID to the file | |
--isolation | Container isolation technology | |
--label | Set metadata for an image | |
-m, --memory | Memory limit | |
--memory-swap | Swap limit equal to memory plus swap: -1 to enable unlimited swap | |
--network | API 1.25+ Set the networking mode for the RUN instructions during build | |
--no-cache | Do not use cache when building the image | |
--platform | API 1.38+ Set platform if server is multi-platform capable | |
--pull | Always attempt to pull a newer version of the image | |
-q, --quiet | Suppress the build output and print image ID on success | |
--rm | true | Remove intermediate containers after a successful build |
--security-opt | Security options | |
--shm-size | Size of /dev/shm | |
--squash | API 1.25+ experimental (daemon) Squash newly built layers into a single new layer | |
-t, --tag | Name and optionally a tag in the name:tag format | |
--target | Set the target build stage to build. | |
--ulimit | Ulimit 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:
Value | Description |
---|---|
default | Use the value specified by the Docker daemon's --exec-opt . If the daemon does not specify an isolation technology, Microsoft Windows uses process as its default value. |
process | Namespace isolation only. |
hyperv | Hyper-V hypervisor partition-based isolation. |
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
.