docker build or
docker buildx build
commands build Docker images from a Dockerfile
and a “context”.
A build’s context is the set of files located at the
as the positional argument to the build command:
$ docker build [OPTIONS] PATH | URL | - ^^^^^^^^^^^^^^
The build process can refer to any of the files in the context. For example,
your build can use a
to reference a file in the context or a
RUN --mount=type=bind instruction
for better performance with BuildKit. The build context
is processed recursively. So, a
PATH includes any subdirectories and the
URL includes the repository and its submodules.
This example shows a build command that uses the current directory (
.) as a
$ docker build . ... #16 [internal] load build context #16 sha256:23ca2f94460dcbaf5b3c3edbaaa933281a4e0ea3d92fe295193e4df44dc68f85 #16 transferring context: 13.16MB 2.2s done ...
With the following Dockerfile:
# syntax=docker/dockerfile:1 FROM busybox WORKDIR /src COPY foo .
And this directory structure:
. ├── Dockerfile ├── bar ├── foo └── node_modules
The legacy builder sends the entire directory to the daemon, including
node_modules directories, even though the
Dockerfile does not use
them. When using BuildKit, the client only sends the
files required by the
COPY instructions, in this case
In some cases you may want to send the entire context:
# syntax=docker/dockerfile:1 FROM busybox WORKDIR /src COPY . .
You can use a
file to exclude some files or directories from being sent:
# .dockerignore node_modules bar
Avoid using your root directory,
/, as the
PATHfor your build context, as it causes the build to transfer the entire contents of your hard drive to the daemon.
URL parameter can refer to three kinds of resources:
- Git repositories
- Pre-packaged tarball contexts
- Plain text files
URL parameter points to the location of a Git repository, the
repository acts as the build context. The builder recursively pulls the
repository and its submodules. A shallow clone is performed and therefore pulls
down just the latest commits, not the entire history. A repository is first
pulled into a temporary directory on your host. After that succeeds, the
directory is sent to the daemon as the context. Local copy gives you the ability
to access private repositories using local user credentials, VPN’s, and so forth.
URLparameter contains a fragment the system will recursively clone the repository and its submodules using a
git clone --recursivecommand.
Git URLs accept a context configuration parameter in the form of a URL fragment,
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
$ docker build https://github.com/user/myrepo.git#container:docker
The following table represents all the valid suffixes with their build contexts:
|Build Syntax Suffix||Commit Used||Build Context Used|
.git directory is not kept on Git checkouts. You can set the
BuildKit built-in arg
to keep it. It can be useful to keep it around if you want to retrieve Git
information during your build:
# syntax=docker/dockerfile:1 FROM alpine WORKDIR /src RUN --mount=target=. \ make REVISION=$(git rev-parse HEAD) build
$ docker build --build-arg BUILDKIT_CONTEXT_KEEP_GIT_DIR=1 https://github.com/user/myrepo.git#main
If you pass a
URL to a remote tarball, the
URL itself is sent to the daemon:
$ docker build http://server/context.tar.gz #1 [internal] load remote build context #1 DONE 0.2s #2 copy /context / #2 DONE 0.1s ...
The download operation will be performed on the host the daemon is running on,
which is not necessarily the same host from which the build command is being
issued. The daemon will fetch
context.tar.gz and use it as the build context.
Tarball contexts must be tar archives conforming to the standard
format and can be compressed with any one of the
identity (no compression) formats.
Instead of specifying a context, you can pass a single
Dockerfile in the
URL or pipe the file in via
STDIN. To pipe a
$ docker build - < Dockerfile
With Powershell on Windows, you can run:
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
option is ignored. In this scenario, there is no context.
The following example builds an image using a
Dockerfile that is passed
through stdin. No files are sent as build context to the daemon.
docker build -t myimage:latest -<<EOF FROM busybox RUN echo "hello world" EOF
Omitting the build context can be useful in situations where your
does not require files to be copied into the image, and improves the build-speed,
as no files are sent to the daemon.