docker-docs/_data/engine-cli/docker_build.yaml

command: docker build
short: Build an image from a Dockerfile
long: |-
  The `docker build` command builds Docker images from a Dockerfile and a
  "context". A build's context is the set of files located in the specified
  `PATH` or `URL`. The build process can refer to any of the files in the
  context. For example, your build can use a [*COPY*](../builder.md#copy)
  instruction to reference a file in the context.

  The `URL` parameter can refer to three kinds of resources: Git repositories,
  pre-packaged tarball contexts and plain text files.

  ### Git repositories

  When the `URL` parameter points to the location of a Git repository, the
  repository acts as the build context. The system recursively fetches the
  repository and its submodules. The commit history is not preserved. A
  repository is first pulled into a temporary directory on your local host. After
  that succeeds, the directory is sent to the Docker daemon as the context.
  Local copy gives you the ability to access private repositories using local
  user credentials, VPN's, and so forth.

  > **Note:**
  > If the `URL` parameter contains a fragment the system will recursively clone
  > the repository and its submodules using a `git clone --recursive` command.

  Git URLs accept context configuration in their fragment section, separated by a
  colon `:`.  The first part represents the reference that Git will check out,
  and can be either a branch, a tag, or a remote reference. The second part
  represents a subdirectory inside the repository that will be used as a build
  context.

  For example, run this command to use a directory called `docker` in the branch
  `container`:

  ```bash
  $ docker build https://github.com/docker/rootfs.git#container:docker
  ```

  The following table represents all the valid suffixes with their build
  contexts:

  Build Syntax Suffix             | Commit Used           | Build Context Used
  --------------------------------|-----------------------|-------------------
  `myrepo.git`                    | `refs/heads/master`   | `/`
  `myrepo.git#mytag`              | `refs/tags/mytag`     | `/`
  `myrepo.git#mybranch`           | `refs/heads/mybranch` | `/`
  `myrepo.git#pull/42/head`       | `refs/pull/42/head`   | `/`
  `myrepo.git#:myfolder`          | `refs/heads/master`   | `/myfolder`
  `myrepo.git#master:myfolder`    | `refs/heads/master`   | `/myfolder`
  `myrepo.git#mytag:myfolder`     | `refs/tags/mytag`     | `/myfolder`
  `myrepo.git#mybranch:myfolder`  | `refs/heads/mybranch` | `/myfolder`


  ### Tarball contexts

  If you pass an URL to a remote tarball, the URL itself is sent to the daemon:

  ```bash
  $ docker build http://server/context.tar.gz
  ```

  The download operation will be performed on the host the Docker daemon is
  running on, which is not necessarily the same host from which the build command
  is being issued. The Docker daemon will fetch `context.tar.gz` and use it as the
  build context. Tarball contexts must be tar archives conforming to the standard
  `tar` UNIX format and can be compressed with any one of the 'xz', 'bzip2',
  'gzip' or 'identity' (no compression) formats.

  ### Text files

  Instead of specifying a context, you can pass a single `Dockerfile` in the
  `URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`:

  ```bash
  $ docker build - < Dockerfile
  ```

  With Powershell on Windows, you can run:

  ```powershell
  Get-Content Dockerfile | docker build -
  ```

  If you use `STDIN` or specify a `URL` pointing to a plain text file, the system
  places the contents into a file called `Dockerfile`, and any `-f`, `--file`
  option is ignored. In this scenario, there is no context.

  By default the `docker build` command will look for a `Dockerfile` at the root
  of the build context. The `-f`, `--file`, option lets you specify the path to
  an alternative file to use instead. This is useful in cases where the same set
  of files are used for multiple builds. The path must be to a file within the
  build context. If a relative path is specified then it is interpreted as
  relative to the root of the context.

  In most cases, it's best to put each Dockerfile in an empty directory. Then,
  add to that directory only the files needed for building the Dockerfile. To
  increase the build's performance, you can exclude files and directories by
  adding a `.dockerignore` file to that directory as well. For information on
  creating one, see the [.dockerignore file](../builder.md#dockerignore-file).

  If the Docker client loses connection to the daemon, the build is canceled.
  This happens if you interrupt the Docker client with `CTRL-c` or if the Docker
  client is killed for any reason. If the build initiated a pull which is still
  running at the time the build is cancelled, the pull is cancelled as well.
usage: docker build [OPTIONS] PATH | URL | -
pname: docker
plink: docker.yaml
options:
- option: add-host
  value_type: list
  description: Add a custom host-to-IP mapping (host:ip)
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: build-arg
  value_type: list
  description: Set build-time variables
  deprecated: 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
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: cgroup-parent
  value_type: string
  description: Optional parent cgroup for the container
  deprecated: 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
  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
  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
  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
  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
  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
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: disable-content-trust
  value_type: bool
  default_value: "true"
  description: Skip image verification
  deprecated: 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')
  deprecated: 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
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: iidfile
  value_type: string
  description: Write the image ID to the file
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: isolation
  value_type: string
  description: Container isolation technology
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: label
  value_type: list
  description: Set metadata for an image
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: memory
  shorthand: m
  value_type: bytes
  default_value: "0"
  description: Memory limit
  deprecated: 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
  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
  deprecated: 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
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: output
  shorthand: o
  value_type: stringArray
  default_value: '[]'
  description: 'Output destination (format: type=local,dest=path)'
  deprecated: false
  min_api_version: "1.40"
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: platform
  value_type: string
  description: Set platform if server is multi-platform capable
  deprecated: false
  min_api_version: "1.32"
  experimental: true
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: progress
  value_type: string
  default_value: auto
  description: |
    Set type of progress output (auto, plain, tty). Use plain to show container output
  deprecated: false
  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
  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
  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
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: secret
  value_type: stringArray
  default_value: '[]'
  description: |
    Secret file to expose to the build (only if BuildKit enabled): id=mysecret,src=/local/secret
  deprecated: false
  min_api_version: "1.39"
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: security-opt
  value_type: stringSlice
  default_value: '[]'
  description: Security options
  deprecated: 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
  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
  deprecated: false
  min_api_version: "1.25"
  experimental: true
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: ssh
  value_type: stringArray
  default_value: '[]'
  description: |
    SSH agent socket or keys to expose to the build (only if BuildKit enabled) (format: default|<id>[=<socket>|<key>[,<key>]])
  deprecated: false
  min_api_version: "1.39"
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: stream
  value_type: bool
  default_value: "false"
  description: Stream attaches to server to negotiate build context
  deprecated: false
  min_api_version: "1.31"
  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
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: target
  value_type: string
  description: Set the target build stage to build.
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
- option: ulimit
  value_type: ulimit
  default_value: '[]'
  description: Ulimit options
  deprecated: false
  experimental: false
  experimentalcli: false
  kubernetes: false
  swarm: false
examples: "### Build with PATH\n\n```bash\n$ docker build .\n\nUploading context 10240
  bytes\nStep 1/3 : FROM busybox\nPulling repository busybox\n ---> e9aa60c60128MB/2.284
  MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/\nStep 2/3 : RUN ls -lh
  /\n ---> Running in 9c9e81692ae9\ntotal 24\ndrwxr-xr-x    2 root     root        4.0K
  Mar 12  2013 bin\ndrwxr-xr-x    5 root     root        4.0K Oct 19 00:19 dev\ndrwxr-xr-x
  \   2 root     root        4.0K Oct 19 00:19 etc\ndrwxr-xr-x    2 root     root
  \       4.0K Nov 15 23:34 lib\nlrwxrwxrwx    1 root     root           3 Mar 12
  \ 2013 lib64 -> lib\ndr-xr-xr-x  116 root     root           0 Nov 15 23:34 proc\nlrwxrwxrwx
  \   1 root     root           3 Mar 12  2013 sbin -> bin\ndr-xr-xr-x   13 root     root
  \          0 Nov 15 23:34 sys\ndrwxr-xr-x    2 root     root        4.0K Mar 12
  \ 2013 tmp\ndrwxr-xr-x    2 root     root        4.0K Nov 15 23:34 usr\n ---> b35f4035db3f\nStep
  3/3 : CMD echo Hello world\n ---> Running in 02071fceb21b\n ---> f52f38b7823e\nSuccessfully
  built f52f38b7823e\nRemoving intermediate container 9c9e81692ae9\nRemoving intermediate
  container 02071fceb21b\n```\n\nThis example specifies that the `PATH` is `.`, and
  so all the files in the\nlocal directory get `tar`d and sent to the Docker daemon.
  The `PATH` specifies\nwhere to find the files for the \"context\" of the build on
  the Docker daemon.\nRemember that the daemon could be running on a remote machine
  and that no\nparsing of the Dockerfile happens at the client side (where you're
  running\n`docker build`). That means that *all* the files at `PATH` get sent, not
  just\nthe ones listed to [*ADD*](../builder.md#add) in the Dockerfile.\n\nThe transfer
  of context from the local machine to the Docker daemon is what the\n`docker` client
  means when you see the \"Sending build context\" message.\n\nIf you wish to keep
  the intermediate containers after the build is complete,\nyou must use `--rm=false`.
  This does not affect the build cache.\n\n### Build with URL\n\n```bash\n$ docker
  build github.com/creack/docker-firefox\n```\n\nThis will clone the GitHub repository
  and use the cloned repository as context.\nThe Dockerfile at the root of the repository
  is used as Dockerfile. You can\nspecify an arbitrary Git repository by using the
  `git://` or `git@` scheme.\n\n```bash\n$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz\n\nDownloading
  context: http://server/ctx.tar.gz [===================>]    240 B/240 B\nStep 1/3
  : FROM busybox\n ---> 8c2e06607696\nStep 2/3 : ADD ctx/container.cfg /\n ---> e7829950cee3\nRemoving
  intermediate container b35224abf821\nStep 3/3 : CMD /bin/ls\n ---> Running in fbc63d321d73\n
  ---> 3286931702ad\nRemoving intermediate container fbc63d321d73\nSuccessfully built
  377c409b35e4\n```\n\nThis sends the URL `http://server/ctx.tar.gz` to the Docker
  daemon, which\ndownloads and extracts the referenced tarball. The `-f ctx/Dockerfile`\nparameter
  specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used\nto build
  the image. Any `ADD` commands in that `Dockerfile` that refers to local\npaths must
  be relative to the root of the contents inside `ctx.tar.gz`. In the\nexample above,
  the tarball contains a directory `ctx/`, so the `ADD\nctx/container.cfg /` operation
  works as expected.\n\n### Build with -\n\n```bash\n$ docker build - < Dockerfile\n```\n\nThis
  will read a Dockerfile from `STDIN` without context. Due to the lack of a\ncontext,
  no contents of any local directory will be sent to the Docker daemon.\nSince there
  is no context, a Dockerfile `ADD` only works if it refers to a\nremote URL.\n\n```bash\n$
  docker build - < context.tar.gz\n```\n\nThis will build an image for a compressed
  context read from `STDIN`.  Supported\nformats are: bzip2, gzip and xz.\n\n### Use
  a .dockerignore file\n\n```bash\n$ docker build .\n\nUploading context 18.829 MB\nUploading
  context\nStep 1/2 : FROM busybox\n ---> 769b9341d937\nStep 2/2 : CMD echo Hello
  world\n ---> Using cache\n ---> 99cc1ad10469\nSuccessfully built 99cc1ad10469\n$
  echo \".git\" > .dockerignore\n$ docker build .\nUploading context  6.76 MB\nUploading
  context\nStep 1/2 : FROM busybox\n ---> 769b9341d937\nStep 2/2 : CMD echo Hello
  world\n ---> Using cache\n ---> 99cc1ad10469\nSuccessfully built 99cc1ad10469\n```\n\nThis
  example shows the use of the `.dockerignore` file to exclude the `.git`\ndirectory
  from the context. Its effect can be seen in the changed size of the\nuploaded context.
  The builder reference contains detailed information on\n[creating a .dockerignore
  file](../builder.md#dockerignore-file)\n\n### Tag an image (-t)\n\n```bash\n$ docker
  build -t vieux/apache:2.0 .\n```\n\nThis will build like the previous example, but
  it will then tag the resulting\nimage. The repository name will be `vieux/apache`
  and the tag will be `2.0`.\n[Read more about valid tags](tag.md).\n\nYou can apply
  multiple tags to an image. For example, you can apply the `latest`\ntag to a newly
  built image and add another tag that references a specific\nversion.\nFor example,
  to tag an image both as `whenry/fedora-jboss:latest` and\n`whenry/fedora-jboss:v2.1`,
  use the following:\n\n```bash\n$ docker build -t whenry/fedora-jboss:latest -t whenry/fedora-jboss:v2.1
  .\n```\n\n### Specify a Dockerfile (-f)\n\n```bash\n$ docker build -f Dockerfile.debug
  .\n```\n\nThis will use a file called `Dockerfile.debug` for the build instructions\ninstead
  of `Dockerfile`.\n\n```bash\n$ curl example.com/remote/Dockerfile | docker build
  -f - .\n```\n\nThe above command will use the current directory as the build context
  and read\na Dockerfile from stdin.\n\n```bash\n$ docker build -f dockerfiles/Dockerfile.debug
  -t myapp_debug .\n$ docker build -f dockerfiles/Dockerfile.prod  -t myapp_prod .\n```\n\nThe
  above commands will build the current build context (as specified by the\n`.`) twice,
  once using a debug version of a `Dockerfile` and once using a\nproduction version.\n\n```bash\n$
  cd /home/me/myapp/some/dir/really/deep\n$ docker build -f /home/me/myapp/dockerfiles/debug
  /home/me/myapp\n$ docker build -f ../../../../dockerfiles/debug /home/me/myapp\n```\n\nThese
  two `docker build` commands do the exact same thing. They both use the\ncontents
  of the `debug` file instead of looking for a `Dockerfile` and will use\n`/home/me/myapp`
  as the root of the build context. Note that `debug` is in the\ndirectory structure
  of the build context, regardless of how you refer to it on\nthe command line.\n\n>
  **Note:**\n> `docker build` will return a `no such file or directory` error if the\n>
  file or directory does not exist in the uploaded context. This may\n> happen if
  there is no context, or if you specify a file that is\n> elsewhere on the Host system.
  The context is limited to the current\n> directory (and its children) for security
  reasons, and to ensure\n> repeatable builds on remote Docker hosts. This is also
  the reason why\n> `ADD ../file` will not work.\n\n### Use a custom parent cgroup
  (--cgroup-parent)\n\nWhen `docker build` is run with the `--cgroup-parent` option
  the containers\nused in the build will be run with the [corresponding `docker run`\nflag](../run.md#specifying-custom-cgroups).\n\n###
  Set ulimits in container (--ulimit)\n\nUsing the `--ulimit` option with `docker
  build` will cause each build step's\ncontainer to be started using those [`--ulimit`\nflag
  values](./run.md#set-ulimits-in-container-ulimit).\n\n### Set build-time variables
  (--build-arg)\n\nYou can use `ENV` instructions in a Dockerfile to define variable\nvalues.
  These values persist in the built image. However, often\npersistence is not what
  you want. Users want to specify variables differently\ndepending on which host they
  build an image on.\n\nA good example is `http_proxy` or source versions for pulling
  intermediate\nfiles. The `ARG` instruction lets Dockerfile authors define values
  that users\ncan set at build-time using the  `--build-arg` flag:\n\n```bash\n$ docker
  build --build-arg HTTP_PROXY=http://10.20.30.2:1234 --build-arg FTP_PROXY=http://40.50.60.5:4567
  .\n```\n\nThis flag allows you to pass the build-time variables that are\naccessed
  like regular environment variables in the `RUN` instruction of the\nDockerfile.
  Also, these values don't persist in the intermediate or final images\nlike `ENV`
  values do.   You must add `--build-arg` for each build argument.  \n\nUsing this
  flag will not alter the output you see when the `ARG` lines from the\nDockerfile
  are echoed during the build process.\n\nFor detailed information on using `ARG`
  and `ENV` instructions, see the\n[Dockerfile reference](../builder.md).\n\nYou may
  also use the `--build-arg` flag without a value, in which case the value\nfrom the
  local environment will be propagated into the Docker container being\nbuilt:\n\n```bash\n$
  export HTTP_PROXY=http://10.20.30.2:1234\n$ docker build --build-arg HTTP_PROXY
  .\n```\n\nThis is similar to how `docker run -e` works. Refer to the [`docker run`
  documentation](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file)\nfor
  more information.\n\n### Optional security options (--security-opt)\n\nThis flag
  is only supported on a daemon running on Windows, and only supports\nthe `credentialspec`
  option. The `credentialspec` must be in the format\n`file://spec.txt` or `registry://keyname`.\n\n###
  Specify isolation technology for container (--isolation)\n\nThis option is useful
  in situations where you are running Docker containers on\nWindows. The `--isolation=<value>`
  option sets a container's isolation\ntechnology. On Linux, the only supported is
  the `default` option which uses\nLinux namespaces. On Microsoft Windows, you can
  specify these values:\n\n\n| Value     | Description                                                                                                                                                   |\n|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|\n|
  `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.  |\n| `process` | Namespace isolation only.                                                                                                                                     |\n|
  `hyperv`  | Hyper-V hypervisor partition-based isolation.                                                                                                                 |\n\nSpecifying
  the `--isolation` flag without a value is the same as setting `--isolation=\"default\"`.\n\n###
  Add entries to container hosts file (--add-host)\n\nYou can add other hosts into
  a container's `/etc/hosts` file by using one or\nmore `--add-host` flags. This example
  adds a static address for a host named\n`docker`:\n\n    $ docker build --add-host=docker:10.180.0.1
  .\n\n### Specifying target build stage (--target)\n\nWhen building a Dockerfile
  with multiple build stages, `--target` can be used to\nspecify an intermediate build
  stage by name as a final stage for the resulting\nimage. Commands after the target
  stage will be skipped.\n\n```Dockerfile\nFROM debian AS build-env\n...\n\nFROM alpine
  AS production-env\n...\n```\n\n```bash\n$ docker build -t mybuildimage --target
  build-env .\n```\n\n### Squash an image's layers (--squash) (experimental)\n\n####
  Overview\n\nOnce the image is built, squash the new layers into a new image with
  a single\nnew layer. Squashing does not destroy any existing image, rather it creates
  a new\nimage with the content of the squashed layers. This effectively makes it
  look\nlike all `Dockerfile` commands were created with a single layer. The build\ncache
  is preserved with this method.\n\nThe `--squash` option is an experimental feature,
  and should not be considered\nstable.\n\n\nSquashing layers can be beneficial if
  your Dockerfile produces multiple layers\nmodifying the same files, for example,
  files that are created in one step, and\nremoved in another step. For other use-cases,
  squashing images may actually have\na negative impact on performance; when pulling
  an image consisting of multiple\nlayers, layers can be pulled in parallel, and allows
  sharing layers between\nimages (saving space).\n\nFor most use cases, multi-stage
  builds are a better alternative, as they give more\nfine-grained control over your
  build, and can take advantage of future\noptimizations in the builder. Refer to
  the [use multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/)\nsection
  in the userguide for more information.\n\n\n#### Known limitations\n\nThe `--squash`
  option has a number of known limitations:\n\n- When squashing layers, the resulting
  image cannot take advantage of layer\n  sharing with other images, and may use significantly
  more space. Sharing the\n  base image is still supported.\n- When using this option
  you may see significantly more space used due to\n  storing two copies of the image,
  one for the build cache with all the cache\n  layers in tact, and one for the squashed
  version.\n- While squashing layers may produce smaller images, it may have a negative\n
  \ impact on performance, as a single layer takes longer to extract, and\n  downloading
  a single layer cannot be parallelized.\n- When attempting to squash an image that
  does not make changes to the\n  filesystem (for example, the Dockerfile only contains
  `ENV` instructions),\n  the squash step will fail (see [issue #33823](https://github.com/moby/moby/issues/33823)).\n\n####
  Prerequisites\n\nThe example on this page is using experimental mode in Docker 1.13.\n\nExperimental
  mode can be enabled by using the `--experimental` flag when starting the Docker
  daemon or setting `experimental: true` in the `daemon.json` configuration file.\n\nBy
  default, experimental mode is disabled. To see the current configuration, use the
  `docker version` command.\n\n```none\nServer:\n Version:      1.13.1\n API version:
  \ 1.26 (minimum version 1.12)\n Go version:   go1.7.5\n Git commit:   092cba3\n
  Built:        Wed Feb  8 06:35:24 2017\n OS/Arch:      linux/amd64\n Experimental:
  false\n\n [...]\n```\n\nTo enable experimental mode, users need to restart the docker
  daemon with the experimental flag enabled.\n\n#### Enable Docker experimental\n\nExperimental
  features are now included in the standard Docker binaries as of version 1.13.0.
  For enabling experimental features, you need to start the Docker daemon with `--experimental`
  flag. You can also enable the daemon flag via /etc/docker/daemon.json. e.g.\n\n```json\n{\n
  \   \"experimental\": true\n}\n```\n\nThen make sure the experimental flag is enabled:\n\n```bash\n$
  docker version -f '{{.Server.Experimental}}'\ntrue\n```\n\n#### Build an image with
  `--squash` argument\n\nThe following is an example of docker build with `--squash`
  argument\n\n```Dockerfile\nFROM busybox\nRUN echo hello > /hello\nRUN echo world
  >> /hello\nRUN touch remove_me /remove_me\nENV HELLO world\nRUN rm /remove_me\n```\n\nAn
  image named `test` is built with `--squash` argument.\n\n```bash\n$ docker build
  --squash -t test .\n\n[...]\n```\n\nIf everything is right, the history will look
  like this:\n\n```bash\n$ docker history test\n\nIMAGE               CREATED             CREATED
  BY                                      SIZE                COMMENT\n4e10cb5b4cac
  \       3 seconds ago                                                       12 B
  \               merge sha256:88a7b0112a41826885df0e7072698006ee8f621c6ab99fca7fe9151d7b599702
  to sha256:47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb\n<missing>
  \          5 minutes ago       /bin/sh -c rm /remove_me                        0
  B\n<missing>           5 minutes ago       /bin/sh -c #(nop) ENV HELLO=world               0
  B\n<missing>           5 minutes ago       /bin/sh -c touch remove_me /remove_me
  \          0 B\n<missing>           5 minutes ago       /bin/sh -c echo world >>
  /hello                 0 B\n<missing>           6 minutes ago       /bin/sh -c echo
  hello > /hello                  0 B\n<missing>           7 weeks ago         /bin/sh
  -c #(nop) CMD [\"sh\"]                    0 B\n<missing>           7 weeks ago         /bin/sh
  -c #(nop) ADD file:47ca6e777c36a4cfff   1.113 MB\n```\n\nWe could find that all
  layer's name is `<missing>`, and there is a new layer with COMMENT `merge`.\n\nTest
  the image, check for `/remove_me` being gone, make sure `hello\\nworld` is in `/hello`,
  make sure the `HELLO` envvar's value is `world`."
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false