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 the 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 description: Add a custom host-to-IP mapping (host:ip) - option: build-arg description: Set build-time variables - option: cache-from default_value: '[]' description: Images to consider as cache sources - option: cgroup-parent description: Optional parent cgroup for the container - option: compress default_value: "false" description: Compress the build context using gzip - option: cpu-period default_value: "0" description: Limit the CPU CFS (Completely Fair Scheduler) period - option: cpu-quota default_value: "0" description: Limit the CPU CFS (Completely Fair Scheduler) quota - option: cpu-shares shorthand: c default_value: "0" description: CPU shares (relative weight) - option: cpuset-cpus description: CPUs in which to allow execution (0-3, 0,1) - option: cpuset-mems description: MEMs in which to allow execution (0-3, 0,1) - option: disable-content-trust default_value: "true" description: Skip image verification - option: file shorthand: f description: Name of the Dockerfile (Default is 'PATH/Dockerfile') - option: force-rm default_value: "false" description: Always remove intermediate containers - option: iidfile description: Write the image ID to the file - option: isolation description: Container isolation technology - option: label description: Set metadata for an image - option: memory shorthand: m default_value: "0" description: Memory limit - option: memory-swap default_value: "0" description: | Swap limit equal to memory plus swap: '-1' to enable unlimited swap - option: network default_value: default description: | Set the networking mode for the RUN instructions during build - option: no-cache default_value: "false" description: Do not use cache when building the image - option: pull default_value: "false" description: Always attempt to pull a newer version of the image - option: quiet shorthand: q default_value: "false" description: Suppress the build output and print image ID on success - option: rm default_value: "true" description: Remove intermediate containers after a successful build - option: security-opt default_value: '[]' description: Security options - option: shm-size default_value: "0" description: Size of /dev/shm - option: squash default_value: "false" description: Squash newly built layers into a single new layer - option: tag shorthand: t description: Name and optionally a tag in the 'name:tag' format - option: target description: Set the target build stage to build. - option: ulimit default_value: '[]' description: Ulimit options 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 .\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.\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\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=` 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 Only**\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\n**Note**: using this option means the new image will not be able to take\nadvantage of layer sharing with other images and may use significantly more\nspace.\n\n**Note**: using this option you may see significantly more space used due to\nstoring two copies of the image, one for the build cache with all the cache\nlayers in tact, and one for the squashed version.\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\n\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```\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```\n\n{\n \ \"experimental\": true\n}\n\n```\nThen make sure the experimental flag is enabled:\n\n```bash\n\n$ docker version -f '{{.Server.Experimental}}'\ntrue\n\n```\n\n#### Build an image with `--squash` argument\n\nThe following is an example of docker build with `--squash` argument\n\n```Dockerfile\n\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\n$ docker build --squash -t test .\n\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 \ 5 minutes ago /bin/sh -c rm /remove_me 0 B\n 5 minutes ago /bin/sh -c #(nop) ENV HELLO=world 0 B\n 5 minutes ago /bin/sh -c touch remove_me /remove_me \ 0 B\n 5 minutes ago /bin/sh -c echo world >> /hello 0 B\n 6 minutes ago /bin/sh -c echo hello > /hello 0 B\n 7 weeks ago /bin/sh -c #(nop) CMD [\"sh\"] 0 B\n 7 weeks ago /bin/sh -c #(nop) ADD file:47ca6e777c36a4cfff 1.113 MB\n\n```\nWe could find that all layer's name is ``, 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`."