mirror of https://github.com/docker/docs.git
539 lines
19 KiB
YAML
539 lines
19 KiB
YAML
command: docker image build
|
|
aliases: docker image build, docker build, docker builder build
|
|
short: Build an image from a Dockerfile
|
|
long: |-
|
|
> [!IMPORTANT]
|
|
> 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`](/reference/cli/docker/build/).
|
|
|
|
When building with legacy builder, images are created from a Dockerfile by
|
|
running a sequence of [commits](/reference/cli/docker/container/commit/). 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`](/reference/cli/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.
|
|
|
|
```console
|
|
$ 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`](/build/concepts/context/#dockerignore-files)
|
|
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.
|
|
|
|
```dockerfile
|
|
FROM alpine
|
|
COPY ../../some-dir .
|
|
```
|
|
|
|
```console
|
|
$ 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.
|
|
usage: docker image build [OPTIONS] PATH | URL | -
|
|
pname: docker image
|
|
plink: docker_image.yaml
|
|
options:
|
|
- option: add-host
|
|
value_type: list
|
|
description: Add a custom host-to-IP mapping (`host:ip`)
|
|
details_url: /reference/cli/docker/buildx/build/#add-host
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: build-arg
|
|
value_type: list
|
|
description: Set build-time variables
|
|
details_url: /reference/cli/docker/buildx/build/#build-arg
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: cache-from
|
|
value_type: stringSlice
|
|
default_value: '[]'
|
|
description: Images to consider as cache sources
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: cgroup-parent
|
|
value_type: string
|
|
description: Set the parent cgroup for the `RUN` instructions during build
|
|
details_url: /reference/cli/docker/buildx/build/#cgroup-parent
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: compress
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Compress the build context using gzip
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: cpu-period
|
|
value_type: int64
|
|
default_value: "0"
|
|
description: Limit the CPU CFS (Completely Fair Scheduler) period
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: cpu-quota
|
|
value_type: int64
|
|
default_value: "0"
|
|
description: Limit the CPU CFS (Completely Fair Scheduler) quota
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: cpu-shares
|
|
shorthand: c
|
|
value_type: int64
|
|
default_value: "0"
|
|
description: CPU shares (relative weight)
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: cpuset-cpus
|
|
value_type: string
|
|
description: CPUs in which to allow execution (0-3, 0,1)
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: cpuset-mems
|
|
value_type: string
|
|
description: MEMs in which to allow execution (0-3, 0,1)
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: disable-content-trust
|
|
value_type: bool
|
|
default_value: "true"
|
|
description: Skip image verification
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: file
|
|
shorthand: f
|
|
value_type: string
|
|
description: Name of the Dockerfile (Default is `PATH/Dockerfile`)
|
|
details_url: /reference/cli/docker/buildx/build/#file
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: force-rm
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Always remove intermediate containers
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: iidfile
|
|
value_type: string
|
|
description: Write the image ID to the file
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: isolation
|
|
value_type: string
|
|
description: Container isolation technology
|
|
details_url: '#isolation'
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: label
|
|
value_type: list
|
|
description: Set metadata for an image
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: memory
|
|
shorthand: m
|
|
value_type: bytes
|
|
default_value: "0"
|
|
description: Memory limit
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: memory-swap
|
|
value_type: bytes
|
|
default_value: "0"
|
|
description: 'Swap limit equal to memory plus swap: -1 to enable unlimited swap'
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: network
|
|
value_type: string
|
|
default_value: default
|
|
description: Set the networking mode for the RUN instructions during build
|
|
details_url: /reference/cli/docker/buildx/build/#network
|
|
deprecated: false
|
|
hidden: false
|
|
min_api_version: "1.25"
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: no-cache
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Do not use cache when building the image
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: platform
|
|
value_type: string
|
|
description: Set platform if server is multi-platform capable
|
|
deprecated: false
|
|
hidden: false
|
|
min_api_version: "1.38"
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: pull
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Always attempt to pull a newer version of the image
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: quiet
|
|
shorthand: q
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Suppress the build output and print image ID on success
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: rm
|
|
value_type: bool
|
|
default_value: "true"
|
|
description: Remove intermediate containers after a successful build
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: security-opt
|
|
value_type: stringSlice
|
|
default_value: '[]'
|
|
description: Security options
|
|
details_url: '#security-opt'
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: shm-size
|
|
value_type: bytes
|
|
default_value: "0"
|
|
description: Size of `/dev/shm`
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: squash
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Squash newly built layers into a single new layer
|
|
details_url: '#squash'
|
|
deprecated: false
|
|
hidden: false
|
|
min_api_version: "1.25"
|
|
experimental: true
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: tag
|
|
shorthand: t
|
|
value_type: list
|
|
description: Name and optionally a tag in the `name:tag` format
|
|
details_url: /reference/cli/docker/buildx/build/#tag
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: target
|
|
value_type: string
|
|
description: Set the target build stage to build.
|
|
details_url: /reference/cli/docker/buildx/build/#target
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
- option: ulimit
|
|
value_type: ulimit
|
|
default_value: '[]'
|
|
description: Ulimit options
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
inherited_options:
|
|
- option: help
|
|
value_type: bool
|
|
default_value: "false"
|
|
description: Print usage
|
|
deprecated: false
|
|
hidden: true
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
examples: |-
|
|
### Specify isolation technology for container (--isolation) {#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. |
|
|
|
|
### Optional security options (--security-opt) {#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) {#squash}
|
|
|
|
#### 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](/build/building/multi-stage/)
|
|
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](https://github.com/moby/moby/issues/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:
|
|
|
|
```console
|
|
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`:
|
|
|
|
```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.
|
|
|
|
```console
|
|
$ 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`.
|
|
|
|
```console
|
|
$ 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`.
|
|
deprecated: false
|
|
hidden: false
|
|
experimental: false
|
|
experimentalcli: false
|
|
kubernetes: false
|
|
swarm: false
|
|
|