Docker can build images automatically by reading the instructions from aDockerfile. A Dockerfile is a text document that contains all the commands auser could call on the command line to assemble an image. This page describesthe commands you can use in a Dockerfile.

Overview

The Dockerfile supports the following instructions:

Format

Here is the format of the Dockerfile:

# CommentINSTRUCTION arguments

The instruction is not case-sensitive. However, convention is for them tobe UPPERCASE to distinguish them from arguments more easily.

Docker runs instructions in a Dockerfile in order. A Dockerfilemustbegin with aFROM instruction. This may be afterparserdirectives,comments, and globally scopedARGs. TheFROM instruction specifies thebaseimage from which you arebuilding.FROM may only be preceded by one or moreARG instructions, whichdeclare arguments that are used inFROM lines in the Dockerfile.

BuildKit treats lines that begin with# as a comment, unless the line isa validparser directive. A# marker anywhereelse in a line is treated as an argument. This allows statements like:

# CommentRUNecho'we are running some # of cool things'

Comment lines are removed before the Dockerfile instructions are executed.The comment in the following example is removed before the shell executestheecho command.

RUNecho hello\# commentworld

The following examples is equivalent.

RUNecho hello\world

Comments don't support line continuation characters.

Note

Note on whitespace

For backward compatibility, leading whitespace before comments (#) andinstructions (such asRUN) are ignored, but discouraged. Leading whitespaceis not preserved in these cases, and the following examples are thereforeequivalent:

# this is a comment-line    RUNecho helloRUNecho world

# this is a comment-lineRUNecho helloRUNecho world

Whitespace in instruction arguments, however, isn't ignored.The following example printshello worldwith leading whitespace as specified:

RUNecho"\     hello\     world"

Parser directives

Parser directives are optional, and affect the way in which subsequent linesin a Dockerfile are handled. Parser directives don't add layers to the build,and don't show up as build steps. Parser directives are written as aspecial type of comment in the form# directive=value. A single directivemay only be used once.

The following parser directives are supported:

• syntax
• escape
• check (since Dockerfile v1.8.0)

Once a comment, empty line or builder instruction has been processed, BuildKitno longer looks for parser directives. Instead it treats anything formattedas a parser directive as a comment and doesn't attempt to validate if it mightbe a parser directive. Therefore, all parser directives must be at thetop of a Dockerfile.

Parser directive keys, such assyntax orcheck, aren't case-sensitive, butthey're lowercase by convention. Values for a directive are case-sensitive andmust be written in the appropriate case for the directive. For example,#check=skip=jsonargsrecommended is invalid because the check name must usePascal case, not lowercase. It's also conventional to include a blank linefollowing any parser directives. Line continuation characters aren't supportedin parser directives.

Due to these rules, the following examples are all invalid:

Invalid due to line continuation:

# direc \tive=value

Invalid due to appearing twice:

# directive=value1# directive=value2FROM ImageName

Treated as a comment because it appears after a builder instruction:

FROM ImageName# directive=value

Treated as a comment because it appears after a comment that isn't a parserdirective:

# About my dockerfile# directive=valueFROM ImageName

The followingunknowndirective is treated as a comment because it isn'trecognized. The knownsyntax directive is treated as a comment because itappears after a comment that isn't a parser directive.

# unknowndirective=value# syntax=value

Non line-breaking whitespace is permitted in a parser directive. Hence, thefollowing lines are all treated identically:

#directive=value# directive =value#directive= value# directive = value#  dIrEcTiVe=value

syntax

Use thesyntax parser directive to declare the Dockerfile syntax version touse for the build. If unspecified, BuildKit uses a bundled version of theDockerfile frontend. Declaring a syntax version lets you automatically use thelatest Dockerfile version without having to upgrade BuildKit or Docker Engine,or even use a custom Dockerfile implementation.

Most users will want to set this parser directive todocker/dockerfile:1,which causes BuildKit to pull the latest stable version of the Dockerfilesyntax before the build.

# syntax=docker/dockerfile:1

For more information about how the parser directive works, seeCustom Dockerfile syntax.

escape

# escape=\

Or

# escape=`

Theescape directive sets the character used to escape characters in aDockerfile. If not specified, the default escape character is\.

The escape character is used both to escape characters in a line, and toescape a newline. This allows a Dockerfile instruction tospan multiple lines. Note that regardless of whether theescape parserdirective is included in a Dockerfile, escaping is not performed inaRUN command, except at the end of a line.

Setting the escape character to` is especially useful onWindows, where\ is the directory path separator.` is consistentwithWindows PowerShell.

Consider the following example which would fail in a non-obvious way onWindows. The second\ at the end of the second line would be interpreted as anescape for the newline, instead of a target of the escape from the first\.Similarly, the\ at the end of the third line would, assuming it was actuallyhandled as an instruction, cause it be treated as a line continuation. The resultof this Dockerfile is that second and third lines are considered a singleinstruction:

FROM microsoft/nanoserverCOPY testfile.txt c:\\RUN dir c:\

Results in:

PS E:\myproject> docker build -t cmd .Sending build context to Docker daemon 3.072 kBStep 1/2 : FROM microsoft/nanoserver ---> 22738ff49c6dStep 2/2 : COPY testfile.txt c:\RUN dir c:GetFileAttributesEx c:RUN: The system cannot find the file specified.PS E:\myproject>

One solution to the above would be to use/ as the target of both theCOPYinstruction, anddir. However, this syntax is, at best, confusing as it is notnatural for paths on Windows, and at worst, error prone as not all commands onWindows support/ as the path separator.

By adding theescape parser directive, the following Dockerfile succeeds asexpected with the use of natural platform semantics for file paths on Windows:

# escape=`FROM microsoft/nanoserverCOPY testfile.txt c:\RUN dir c:\

Results in:

PS E:\myproject> docker build -t succeeds --no-cache=true .Sending build context to Docker daemon 3.072 kBStep 1/3 : FROM microsoft/nanoserver ---> 22738ff49c6dStep 2/3 : COPY testfile.txt c:\ ---> 96655de338deRemoving intermediate container 4db9acbb1682Step 3/3 : RUN dir c:\ ---> Running in a2c157f842f5 Volume in drive C has no label. Volume Serial Number is 7E6D-E0F7 Directory of c:\10/05/2016  05:04 PM             1,894 License.txt10/05/2016  02:22 PM    <DIR>          Program Files10/05/2016  02:14 PM    <DIR>          Program Files (x86)10/28/2016  11:18 AM                62 testfile.txt10/28/2016  11:20 AM    <DIR>          Users10/28/2016  11:20 AM    <DIR>          Windows           2 File(s)          1,956 bytes           4 Dir(s)  21,259,096,064 bytes free ---> 01c7f3bef04fRemoving intermediate container a2c157f842f5Successfully built 01c7f3bef04fPS E:\myproject>

check

# check=skip=<checks|all># check=error=<boolean>

Thecheck directive is used to configure howbuild checksare evaluated. By default, all checks are run, and failures are treated aswarnings.

You can disable specific checks using#check=skip=<check-name>. To specifymultiple checks to skip, separate them with a comma:

# check=skip=JSONArgsRecommended,StageNameCasing

To disable all checks, use#check=skip=all.

By default, builds with failing build checks exit with a zero status codedespite warnings. To make the build fail on warnings, set#check=error=true.

# check=error=true

Note

When using thecheck directive, witherror=true option, it is recommendedto pin theDockerfile syntax to a specific version. Otherwise, your build maystart to fail when new checks are added in the future versions.

To combine both theskip anderror options, use a semi-colon to separatethem:

# check=skip=JSONArgsRecommended;error=true

To see all available checks, see thebuild checks reference.Note that the checks available depend on the Dockerfile syntax version. To makesure you're getting the most up-to-date checks, use thesyntaxdirective to specify the Dockerfile syntax version to the latest stableversion.

Environment replacement

Environment variables (declared withtheENV statement) can also beused in certain instructions as variables to be interpreted by theDockerfile. Escapes are also handled for including variable-like syntaxinto a statement literally.

Environment variables are notated in the Dockerfile either with$variable_name or${variable_name}. They are treated equivalently and thebrace syntax is typically used to address issues with variable names with nowhitespace, like${foo}_bar.

The${variable_name} syntax also supports a few of the standardbashmodifiers as specified below:

• ${variable:-word} indicates that ifvariable is set then the resultwill be that value. Ifvariable is not set thenword will be the result.
• ${variable:+word} indicates that ifvariable is set thenword will bethe result, otherwise the result is the empty string.

The following variable replacements are supported in a pre-release version ofDockerfile syntax, when using the# syntax=docker/dockerfile-upstream:master syntaxdirective in your Dockerfile:

• ${variable#pattern} removes the shortest match ofpattern fromvariable,seeking from the start of the string.

  str=foobarbazecho${str#f*b}# arbaz

• ${variable##pattern} removes the longest match ofpattern fromvariable,seeking from the start of the string.

  str=foobarbazecho${str##f*b}# az

• ${variable%pattern} removes the shortest match ofpattern fromvariable,seeking backwards from the end of the string.

  string=foobarbazecho${string%b*}# foobar

• ${variable%%pattern} removes the longest match ofpattern fromvariable,seeking backwards from the end of the string.

  string=foobarbazecho${string%%b*}# foo

• ${variable/pattern/replacement} replace the first occurrence ofpatterninvariable withreplacement

  string=foobarbazecho${string/ba/fo}# fooforbaz

• ${variable//pattern/replacement} replaces all occurrences ofpatterninvariable withreplacement

  string=foobarbazecho${string//ba/fo}# fooforfoz

In all cases,word can be any string, including additional environmentvariables.

pattern is a glob pattern where? matches any single characterand* any number of characters (including zero). To match literal? and*,use a backslash escape:\? and\*.

You can escape whole variable names by adding a\ before the variable:\$foo or\${foo},for example, will translate to$foo and${foo} literals respectively.

Example (parsed representation is displayed after the#):

FROM busyboxENVFOO=/barWORKDIR ${FOO}   # WORKDIR /barADD .$FOO# ADD . /barCOPY\$FOO /quux# COPY $FOO /quux

Environment variables are supported by the following list of instructions inthe Dockerfile:

• ADD
• COPY
• ENV
• EXPOSE
• FROM
• LABEL
• STOPSIGNAL
• USER
• VOLUME
• WORKDIR
• ONBUILD (when combined with one of the supported instructions above)

You can also use environment variables withRUN,CMD, andENTRYPOINTinstructions, but in those cases the variable substitution is handled by thecommand shell, not the builder. Note that instructions using the exec formdon't invoke a command shell automatically. SeeVariablesubstitution.

Environment variable substitution use the same value for each variablethroughout the entire instruction. Changing the value of a variable only takeseffect in subsequent instructions. Consider the following example:

ENVabc=helloENVabc=byedef=$abcENVghi=$abc

• The value ofdef becomeshello
• The value ofghi becomesbye

.dockerignore file

You can use.dockerignore file to exclude files and directories from thebuild context. For more information, see.dockerignore file.

Shell and exec form

TheRUN,CMD, andENTRYPOINT instructions all have two possible forms:

• INSTRUCTION ["executable","param1","param2"] (exec form)
• INSTRUCTION command param1 param2 (shell form)

The exec form makes it possible to avoid shell string munging, and to invokecommands using a specific command shell, or any other executable. It uses aJSON array syntax, where each element in the array is a command, flag, orargument.

The shell form is more relaxed, and emphasizes ease of use, flexibility, andreadability. The shell form automatically uses a command shell, whereas theexec form does not.

Exec form

The exec form is parsed as a JSON array, which means thatyou must use double-quotes (") around words, not single-quotes (').

ENTRYPOINT["/bin/bash","-c","echo hello"]

The exec form is best used to specify anENTRYPOINT instruction, combinedwithCMD for setting default arguments that can be overridden at runtime. Formore information, seeENTRYPOINT.

Variable substitution

Using the exec form doesn't automatically invoke a command shell. This meansthat normal shell processing, such as variable substitution, doesn't happen.For example,RUN [ "echo", "$HOME" ] won't handle variable substitution for$HOME.

If you want shell processing then either use the shell form or execute a shelldirectly with the exec form, for example:RUN [ "sh", "-c", "echo $HOME" ].When using the exec form and executing a shell directly, as in the case for theshell form, it's the shell that's doing the environment variable substitution,not the builder.

Backslashes

In exec form, you must escape backslashes. This is particularly relevant onWindows where the backslash is the path separator. The following line wouldotherwise be treated as shell form due to not being valid JSON, and fail in anunexpected way:

RUN["c:\windows\system32\tasklist.exe"]

The correct syntax for this example is:

RUN["c:\\windows\\system32\\tasklist.exe"]

Shell form

Unlike the exec form, instructions using the shell form always use a commandshell. The shell form doesn't use the JSON array format, instead it's a regularstring. The shell form string lets you escape newlines using theescapecharacter (backslash by default) to continue a single instructiononto the next line. This makes it easier to use with longer commands, becauseit lets you split them up into multiple lines. For example, consider these twolines:

RUNsource$HOME/.bashrc&&\echo$HOME

They're equivalent to the following line:

RUNsource$HOME/.bashrc&&echo$HOME

You can also use heredocs with the shell form to break up supported commands.

RUN <<EOFsource$HOME/.bashrc&&\echo$HOMEEOF

For more information about heredocs, seeHere-documents.

Use a different shell

You can change the default shell using theSHELL command. For example:

SHELL["/bin/bash","-c"]RUNecho hello

For more information, seeSHELL.

FROM

FROM [--platform=<platform>] <image> [AS <name>]

Or

FROM [--platform=<platform>] <image>[:<tag>] [AS <name>]

Or

FROM [--platform=<platform>] <image>[@<digest>] [AS <name>]

TheFROM instruction initializes a new build stage and sets thebase image for subsequentinstructions. As such, a valid Dockerfile must start with aFROM instruction.The image can be any valid image.

• ARG is the only instruction that may precedeFROM in the Dockerfile.SeeUnderstand how ARG and FROM interact.
• FROM can appear multiple times within a single Dockerfile tocreate multiple images or use one build stage as a dependency for another.Simply make a note of the last image ID output by the commit before each newFROM instruction. EachFROM instruction clears any state created by previousinstructions.
• Optionally a name can be given to a new build stage by addingAS name to theFROM instruction. The name can be used in subsequentFROM <name>,COPY --from=<name>,andRUN --mount=type=bind,from=<name> instructionsto refer to the image built in this stage.
• Thetag ordigest values are optional. If you omit either of them, thebuilder assumes alatest tag by default. The builder returns an error if itcan't find thetag value.

The optional--platform flag can be used to specify the platform of the imagein caseFROM references a multi-platform image. For example,linux/amd64,linux/arm64, orwindows/amd64. By default, the target platform of the buildrequest is used. Global build arguments can be used in the value of this flag,for exampleautomatic platform ARGsallow you to force a stage to native build platform (--platform=$BUILDPLATFORM),and use it to cross-compile to the target platform inside the stage.

Understand how ARG and FROM interact

FROM instructions support variables that are declared by anyARGinstructions that occur before the firstFROM.

ARGCODE_VERSION=latestFROM base:${CODE_VERSION}CMD  /code/run-appFROM extras:${CODE_VERSION}CMD  /code/run-extras

AnARG declared before aFROM is outside of a build stage, so itcan't be used in any instruction after aFROM. To use the default value ofanARG declared before the firstFROM use anARG instruction withouta value inside of a build stage:

ARGVERSION=latestFROM busybox:$VERSIONARG VERSIONRUNecho$VERSION > image_version

RUN

TheRUN instruction will execute any commands to create a new layer on top ofthe current image. The added layer is used in the next step in the Dockerfile.RUN has two forms:

# Shell form:RUN[OPTIONS] <command> ...# Exec form:RUN[OPTIONS]["<command>", ...]

For more information about the differences between these two forms, seeshell or exec forms.

The shell form is most commonly used, and lets you break up longerinstructions into multiple lines, either using newlineescapes, orwithheredocs:

RUN <<EOFapt-get updateapt-get install -y curlEOF

The available[OPTIONS] for theRUN instruction are:

Cache invalidation for RUN instructions

The cache forRUN instructions isn't invalidated automatically duringthe next build. The cache for an instruction likeRUN apt-get dist-upgrade -y will be reused during the next build. Thecache forRUN instructions can be invalidated by using the--no-cacheflag, for exampledocker build --no-cache.

See theDockerfile Best Practicesguide for more information.

The cache forRUN instructions can be invalidated byADD andCOPY instructions.

RUN --device

Note

Not yet available in stable syntax, usedocker/dockerfile:1-labsversion. It also needs BuildKit 0.20.0 or later.

RUN --device=name,[required]

RUN --device allows build to requestCDI devicesto be available to the build step.

The devicename is provided by the CDI specification registered in BuildKit.

In the following example, multiple devices are registered in the CDIspecification for thevendor1.com/device vendor.

cdiVersion:"0.6.0"kind:"vendor1.com/device"devices:-name:foocontainerEdits:env:-FOO=injected-name:barannotations:org.mobyproject.buildkit.device.class:class1containerEdits:env:-BAR=injected-name:bazannotations:org.mobyproject.buildkit.device.class:class1containerEdits:env:-BAZ=injected-name:quxannotations:org.mobyproject.buildkit.device.class:class2containerEdits:env:-QUX=injected

The device name format is flexible and accepts various patterns to supportmultiple device configurations:

• vendor1.com/device: request the first device found for this vendor
• vendor1.com/device=foo: request a specific device
• vendor1.com/device=*: request all devices for this vendor
• class1: request devices byorg.mobyproject.buildkit.device.class annotation

Example: CUDA-Powered LLaMA Inference

In this example we use the--device flag to runllama.cpp inference usingan NVIDIA GPU device through CDI:

# syntax=docker/dockerfile:1-labsFROM scratch AS modelADD https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf /model.ggufFROM scratch AS promptCOPY <<EOF prompt.txtQ: Generate  a list of10 unique biggest countries by population in JSON with their estimated poulation in1900 and 2024. Answer only newline formatted JSON with keys"country","population_1900","population_2024" with10 items.A:[{EOFFROM ghcr.io/ggml-org/llama.cpp:full-cuda-b5124RUN --device=nvidia.com/gpu=all\    --mount=from=model,target=/models\    --mount=from=prompt,target=/tmp\    ./llama-cli -m /models/model.gguf -no-cnv -ngl99 -f /tmp/prompt.txt

RUN --mount

RUN --mount=[type=<TYPE>][,option=<value>[,option=<value>]...]

RUN --mount allows you to create filesystem mounts that the build can access.This can be used to:

• Create bind mount to the host filesystem or other build stages
• Access build secrets or ssh-agent sockets
• Use a persistent package management cache to speed up your build

The supported mount types are:

RUN --mount=type=bind

This mount type allows binding files or directories to the build container. Abind mount is read-only by default.

RUN --mount=type=cache

This mount type allows the build container to cache directories for compilersand package managers.

Contents of the cache directories persists between builder invocations withoutinvalidating the instruction cache. Cache mounts should only be used for betterperformance. Your build should work with any contents of the cache directory asanother build may overwrite the files or GC may clean it if more storage spaceis needed.

Example: cache Go packages

# syntax=docker/dockerfile:1FROM golangRUN --mount=type=cache,target=/root/.cache/go-build\  go build ...

Example: cache apt packages

# syntax=docker/dockerfile:1FROM ubuntuRUN rm -f /etc/apt/apt.conf.d/docker-clean;echo'Binary::apt::APT::Keep-Downloaded-Packages "true";' > /etc/apt/apt.conf.d/keep-cacheRUN --mount=type=cache,target=/var/cache/apt,sharing=locked\  --mount=type=cache,target=/var/lib/apt,sharing=locked\  apt update&& apt-get --no-install-recommends install -y gcc

Apt needs exclusive access to its data, so the caches use the optionsharing=locked, which will make sure multiple parallel builds usingthe same cache mount will wait for each other and not access the samecache files at the same time. You could also usesharing=private ifyou prefer to have each build create another cache directory in thiscase.

RUN --mount=type=tmpfs

This mount type allows mountingtmpfs in the build container.

RUN --mount=type=secret

This mount type allows the build container to access secret values, such astokens or private keys, without baking them into the image.

By default, the secret is mounted as a file. You can also mount the secret asan environment variable by setting theenv option.

Example: access to S3

# syntax=docker/dockerfile:1FROM python:3RUN pip install awscliRUN --mount=type=secret,id=aws,target=/root/.aws/credentials\  aws s3 cp s3://... ...

$ docker buildx build --secretid=aws,src=$HOME/.aws/credentials .

Example: Mount as environment variable

The following example takes the secretAPI_KEY and mounts it as anenvironment variable with the same name.

# syntax=docker/dockerfile:1FROM alpineRUN --mount=type=secret,id=API_KEY,env=API_KEY\    some-command --token-from-env$API_KEY

Assuming that theAPI_KEY environment variable is set in the buildenvironment, you can build this with the following command:

$ docker buildx build --secretid=API_KEY .

RUN --mount=type=ssh

This mount type allows the build container to access SSH keys via SSH agents,with support for passphrases.

Example: access to GitLab

# syntax=docker/dockerfile:1FROM alpineRUN apk add --no-cache openssh-clientRUN mkdir -p -m0700 ~/.ssh&& ssh-keyscan gitlab.com >> ~/.ssh/known_hostsRUN --mount=type=ssh\  ssh -q -T git@gitlab.com 2>&1| tee /hello# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here# with the type of build progress is defined as `plain`.

$eval$(ssh-agent)$ ssh-add ~/.ssh/id_rsa(Input your passphrase here)$ docker buildx build --sshdefault=$SSH_AUTH_SOCK .

You can also specify a path to*.pem file on the host directly instead of$SSH_AUTH_SOCK.However, pem files with passphrases are not supported.

RUN --network

RUN --network=<TYPE>

RUN --network allows control over which networking environment the commandis run in.

The supported network types are:

RUN --network=default

Equivalent to not supplying a flag at all, the command is run in the defaultnetwork for the build.

RUN --network=none

The command is run with no network access (lo is still available, but isisolated to this process)

Example: isolating external effects

# syntax=docker/dockerfile:1FROM python:3.6ADD mypackage.tgz wheels/RUN --network=none pip install --find-links wheels mypackage

pip will only be able to install the packages provided in the tarfile, whichcan be controlled by an earlier build stage.

RUN --network=host

The command is run in the host's network environment (similar todocker build --network=host, but on a per-instruction basis)

Warning

The use of--network=host is protected by thenetwork.host entitlement,which needs to be enabled when starting the buildkitd daemon with--allow-insecure-entitlement network.host flag or inbuildkitd config,and for a build request with--allow network.host flag.

RUN --security

Note

Not yet available in stable syntax, usedocker/dockerfile:1-labs version.

RUN --security=<sandbox|insecure>

The default security mode issandbox.With--security=insecure, the builder runs the command without sandbox in insecuremode, which allows to run flows requiring elevated privileges (e.g. containerd).This is equivalent to runningdocker run --privileged.

Warning

In order to access this feature, entitlementsecurity.insecure should beenabled when starting the buildkitd daemon with--allow-insecure-entitlement security.insecure flag or inbuildkitd config,and for a build request with--allow security.insecure flag.

Default sandbox mode can be activated via--security=sandbox, but that is no-op.

Example: check entitlements

# syntax=docker/dockerfile:1-labsFROM ubuntuRUN --security=insecure cat /proc/self/status| grep CapEff

#84 0.093 CapEff:0000003fffffffff

CMD

TheCMD instruction sets the command to be executed when running a containerfrom an image.

You can specifyCMD instructions usingshell or exec forms:

• CMD ["executable","param1","param2"] (exec form)
• CMD ["param1","param2"] (exec form, as default parameters toENTRYPOINT)
• CMD command param1 param2 (shell form)

There can only be oneCMD instruction in a Dockerfile. If you list more thanoneCMD, only the last one takes effect.

The purpose of aCMD is to provide defaults for an executing container. Thesedefaults can include an executable, or they can omit the executable, in whichcase you must specify anENTRYPOINT instruction as well.

If you would like your container to run the same executable every time, thenyou should consider usingENTRYPOINT in combination withCMD. SeeENTRYPOINT. If the user specifies arguments todocker runthen they will override the default specified inCMD, but still use thedefaultENTRYPOINT.

IfCMD is used to provide default arguments for theENTRYPOINT instruction,both theCMD andENTRYPOINT instructions should be specified in theexec form.

Note

Don't confuseRUN withCMD.RUN actually runs a command and commitsthe result;CMD doesn't execute anything at build time, but specifiesthe intended command for the image.

LABEL

LABEL <key>=<value>[<key>=<value>...]

TheLABEL instruction adds metadata to an image. ALABEL is akey-value pair. To include spaces within aLABEL value, use quotes andbackslashes as you would in command-line parsing. A few usage examples:

LABEL"com.example.vendor"="ACME Incorporated"LABEL com.example.label-with-value="foo"LABELversion="1.0"LABELdescription="This text illustrates \that label-values can span multiple lines."

An image can have more than one label. You can specify multiple labels on asingle line. Prior to Docker 1.10, this decreased the size of the final image,but this is no longer the case. You may still choose to specify multiple labelsin a single instruction, in one of the following two ways:

LABEL multi.label1="value1" multi.label2="value2"other="value3"

LABEL multi.label1="value1"\      multi.label2="value2"\other="value3"

Note

Be sure to use double quotes and not single quotes. Particularly when you areusing string interpolation (e.g.LABEL example="foo-$ENV_VAR"), singlequotes will take the string as is without unpacking the variable's value.

Labels included in base images (images in theFROM line) are inherited byyour image. If a label already exists but with a different value, themost-recently-applied value overrides any previously-set value.

To view an image's labels, use thedocker image inspect command. You can usethe--format option to show just the labels;

$ docker image inspect --format='{{json .Config.Labels}}' myimage

{"com.example.vendor":"ACME Incorporated","com.example.label-with-value":"foo","version":"1.0","description":"This text illustrates that label-values can span multiple lines.","multi.label1":"value1","multi.label2":"value2","other":"value3"}

MAINTAINER (deprecated)

MAINTAINER <name>

TheMAINTAINER instruction sets theAuthor field of the generated images.TheLABEL instruction is a much more flexible version of this and you should useit instead, as it enables setting any metadata you require, and can be viewedeasily, for example withdocker inspect. To set a label corresponding to theMAINTAINER field you could use:

LABEL org.opencontainers.image.authors="SvenDowideit@home.org.au"

This will then be visible fromdocker inspect with the other labels.

EXPOSE

EXPOSE <port> [<port>/<protocol>...]

TheEXPOSE instruction informs Docker that the container listens on thespecified network ports at runtime. You can specify whether the port listens onTCP or UDP, and the default is TCP if you don't specify a protocol.

TheEXPOSE instruction doesn't actually publish the port. It functions as atype of documentation between the person who builds the image and the person whoruns the container, about which ports are intended to be published. Topublish the port when running the container, use the-p flag ondocker runto publish and map one or more ports, or the-P flag to publish all exposedports and map them to high-order ports.

By default,EXPOSE assumes TCP. You can also specify UDP:

EXPOSE 80/udp

To expose on both TCP and UDP, include two lines:

EXPOSE 80/tcpEXPOSE 80/udp

In this case, if you use-P withdocker run, the port will be exposed oncefor TCP and once for UDP. Remember that-P uses an ephemeral high-ordered hostport on the host, so TCP and UDP doesn't use the same port.

Regardless of theEXPOSE settings, you can override them at runtime by usingthe-p flag. For example

$ docker run -p 80:80/tcp -p 80:80/udp ...

To set up port redirection on the host system, seeusing the -P flag.Thedocker network command supports creating networks for communication amongcontainers without the need to expose or publish specific ports, because thecontainers connected to the network can communicate with each other over anyport. For detailed information, see theoverview of this feature.

ENV

ENV <key>=<value>[<key>=<value>...]

TheENV instruction sets the environment variable<key> to the value<value>. This value will be in the environment for all subsequent instructionsin the build stage and can bereplaced inline inmany as well. The value will be interpreted for other environment variables, soquote characters will be removed if they are not escaped. Like command line parsing,quotes and backslashes can be used to include spaces within values.

Example:

ENVMY_NAME="John Doe"ENVMY_DOG=Rex\The\DogENVMY_CAT=fluffy

TheENV instruction allows for multiple<key>=<value> ... variables to be setat one time, and the example below will yield the same net results in the finalimage:

ENVMY_NAME="John Doe"MY_DOG=Rex\The\Dog\MY_CAT=fluffy

The environment variables set usingENV will persist when a container is runfrom the resulting image. You can view the values usingdocker inspect, andchange them usingdocker run --env <key>=<value>.

A stage inherits any environment variables that were set usingENV by itsparent stage or any ancestor. Refer to themulti-stage builds sectionin the manual for more information.

Environment variable persistence can cause unexpected side effects. For example,settingENV DEBIAN_FRONTEND=noninteractive changes the behavior ofapt-get,and may confuse users of your image.

If an environment variable is only needed during build, and not in the finalimage, consider setting a value for a single command instead:

RUNDEBIAN_FRONTEND=noninteractive apt-get update&& apt-get install -y ...

Or usingARG, which is not persisted in the final image:

ARGDEBIAN_FRONTEND=noninteractiveRUN apt-get update&& apt-get install -y ...

Note

Alternative syntax

TheENV instruction also allows an alternative syntaxENV <key> <value>,omitting the=. For example:

ENV MY_VAR my-value

This syntax does not allow for multiple environment-variables to be set in asingleENV instruction, and can be confusing. For example, the followingsets a single environment variable (ONE) with value"TWO= THREE=world":

ENV ONETWO=THREE=world

The alternative syntax is supported for backward compatibility, but discouragedfor the reasons outlined above, and may be removed in a future release.

ADD

ADD has two forms.The latter form is required for paths containing whitespace.

ADD[OPTIONS] <src> ... <dest>ADD[OPTIONS]["<src>", ..."<dest>"]

The available[OPTIONS] are:

TheADD instruction copies new files or directories from<src> and addsthem to the filesystem of the image at the path<dest>. Files and directoriescan be copied from the build context, a remote URL, or a Git repository.

TheADD andCOPY instructions are functionally similar, but serve slightly different purposes.Learn more about thedifferences betweenADD andCOPY.

Source

You can specify multiple source files or directories withADD. The lastargument must always be the destination. For example, to add two files,file1.txt andfile2.txt, from the build context to/usr/src/things/ inthe build container:

ADD file1.txt file2.txt /usr/src/things/

If you specify multiple source files, either directly or using a wildcard, thenthe destination must be a directory (must end with a slash/).

To add files from a remote location, you can specify a URL or the address of aGit repository as the source. For example:

ADD https://example.com/archive.zip /usr/src/things/ADD git@github.com:user/repo.git /usr/src/things/

BuildKit detects the type of<src> and processes it accordingly.

• If<src> is a local file or directory, the contents of the directory arecopied to the specified destination. SeeAdding files from the build context.
• If<src> is a local tar archive, it is decompressed and extracted to thespecified destination. SeeAdding local tar archives.
• If<src> is a URL, the contents of the URL are downloaded and placed atthe specified destination. SeeAdding files from a URL.
• If<src> is a Git repository, the repository is cloned to the specifieddestination. SeeAdding files from a Git repository.

Adding files from the build context

Any relative or local path that doesn't begin with ahttp://,https://, orgit@ protocol prefix is considered a local file path. The local file path isrelative to the build context. For example, if the build context is the currentdirectory,ADD file.txt / adds the file at./file.txt to the root of thefilesystem in the build container.

Specifying a source path with a leading slash or one that navigates outside thebuild context, such asADD ../something /something, automatically removes anyparent directory navigation (../). Trailing slashes in the source path arealso disregarded, makingADD something/ /something equivalent toADD something /something.

If the source is a directory, the contents of the directory are copied,including filesystem metadata. The directory itself isn't copied, only itscontents. If it contains subdirectories, these are also copied, and merged withany existing directories at the destination. Any conflicts are resolved infavor of the content being added, on a file-by-file basis, except if you'retrying to copy a directory onto an existing file, in which case an error israised.

If the source is a file, the file and its metadata are copied to thedestination. File permissions are preserved. If the source is a file and adirectory with the same name exists at the destination, an error is raised.

If you pass a Dockerfile through stdin to the build (docker build - < Dockerfile), there is no build context. In this case, you can only use theADD instruction to copy remote files. You can also pass a tar archive throughstdin: (docker build - < archive.tar), the Dockerfile at the root of thearchive and the rest of the archive will be used as the context of the build.

Pattern matching

For local files, each<src> may contain wildcards and matching will be doneusing Go'sfilepath.Match rules.

For example, to add all files and directories in the root of the build contextending with.png:

ADD *.png /dest/

In the following example,? is a single-character wildcard, matching e.g.index.js andindex.ts.

ADD index.?s /dest/

When adding files or directories that contain special characters (such as[and]), you need to escape those paths following the Golang rules to preventthem from being treated as a matching pattern. For example, to add a filenamedarr[0].txt, use the following;

ADD arr[[]0].txt /dest/

Adding local tar archives

When using a local tar archive as the source forADD, and the archive is in arecognized compression format (gzip,bzip2 orxz, or uncompressed), thearchive is decompressed and extracted into the specified destination. Onlylocal tar archives are extracted. If the tar archive is a remote URL, thearchive is not extracted, but downloaded and placed at the destination.

When a directory is extracted, it has the same behavior astar -x.The result is the union of:

1. Whatever existed at the destination path, and
2. The contents of the source tree, with conflicts resolved in favor of thecontent being added, on a file-by-file basis.

Note

Whether a file is identified as a recognized compression format or not isdone solely based on the contents of the file, not the name of the file. Forexample, if an empty file happens to end with.tar.gz this isn't recognizedas a compressed file and doesn't generate any kind of decompression errormessage, rather the file will simply be copied to the destination.

Adding files from a URL

In the case where source is a remote file URL, the destination will havepermissions of 600. If the HTTP response contains aLast-Modified header, thetimestamp from that header will be used to set themtime on the destinationfile. However, like any other file processed during anADD,mtime isn'tincluded in the determination of whether or not the file has changed and thecache should be updated.

If the destination ends with a trailing slash, then the filename is inferredfrom the URL path. For example,ADD http://example.com/foobar / would createthe file/foobar. The URL must have a nontrivial path so that an appropriatefilename can be discovered (http://example.com doesn't work).

If the destination doesn't end with a trailing slash, the destination pathbecomes the filename of the file downloaded from the URL. For example,ADD http://example.com/foo /bar creates the file/bar.

If your URL files are protected using authentication, you need to useRUN wget,RUN curl or use another tool from within the container as theADD instructiondoesn't support authentication.

Adding files from a Git repository

To use a Git repository as the source forADD, you can reference therepository's HTTP or SSH address as the source. The repository is cloned to thespecified destination in the image.

ADD https://github.com/user/repo.git /mydir/

You can use URL fragments to specify a specific branch, tag, commit, orsubdirectory. For example, to add thedocs directory of thev0.14.1 tag ofthebuildkit repository:

ADD git@github.com:moby/buildkit.git#v0.14.1:docs /buildkit-docs

For more information about Git URL fragments,seeURL fragments.

When adding from a Git repository, the permissions bits for filesare 644. If a file in the repository has the executable bit set, it will havepermissions set to 755. Directories have permissions set to 755.

When using a Git repository as the source, the repository must be accessiblefrom the build context. To add a repository via SSH, whether public or private,you must pass an SSH key for authentication. For example, given the followingDockerfile:

# syntax=docker/dockerfile:1FROM alpineADD git@git.example.com:foo/bar.git /bar

To build this Dockerfile, pass the--ssh flag to thedocker build to mountthe SSH agent socket to the build. For example:

$ docker build --ssh default .

For more information about building with secrets,seeBuild secrets.

Destination

If the destination path begins with a forward slash, it's interpreted as anabsolute path, and the source files are copied into the specified destinationrelative to the root of the current build stage.

# create /abs/test.txtADD test.txt /abs/

Trailing slashes are significant. For example,ADD test.txt /abs creates afile at/abs, whereasADD test.txt /abs/ creates/abs/test.txt.

If the destination path doesn't begin with a leading slash, it's interpreted asrelative to the working directory of the build container.

WORKDIR /usr/src/app# create /usr/src/app/rel/test.txtADD test.txt rel/

If destination doesn't exist, it's created, along with all missing directoriesin its path.

If the source is a file, and the destination doesn't end with a trailing slash,the source file will be written to the destination path as a file.

ADD --keep-git-dir

ADD[--keep-git-dir=<boolean>] <src> ... <dir>

When<src> is the HTTP or SSH address of a remote Git repository,BuildKit adds the contents of the Git repository to the imageexcluding the.git directory by default.

The--keep-git-dir=true flag lets you preserve the.git directory.

# syntax=docker/dockerfile:1FROM alpineADD --keep-git-dir=true https://github.com/moby/buildkit.git#v0.10.1 /buildkit

ADD --checksum

ADD[--checksum=<hash>] <src> ... <dir>

The--checksum flag lets you verify the checksum of a remote resource. Thechecksum is formatted assha256:<hash>. SHA-256 is the only supported hashalgorithm.

ADD --checksum=sha256:24454f830cdb571e2c4ad15481119c43b3cafd48dd869a9b2945d1036d1dc68d https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz /

The--checksum flag only supports HTTP(S) sources.

ADD --chown --chmod

SeeCOPY --chown --chmod.

ADD --link

SeeCOPY --link.

ADD --exclude

SeeCOPY --exclude.

COPY

COPY has two forms.The latter form is required for paths containing whitespace.

COPY[OPTIONS] <src> ... <dest>COPY[OPTIONS]["<src>", ..."<dest>"]

The available[OPTIONS] are:

TheCOPY instruction copies new files or directories from<src> and addsthem to the filesystem of the image at the path<dest>. Files and directoriescan be copied from the build context, build stage, named context, or an image.

TheADD andCOPY instructions are functionally similar, but serve slightly different purposes.Learn more about thedifferences betweenADD andCOPY.

Source

You can specify multiple source files or directories withCOPY. The lastargument must always be the destination. For example, to copy two files,file1.txt andfile2.txt, from the build context to/usr/src/things/ inthe build container:

COPY file1.txt file2.txt /usr/src/things/

If you specify multiple source files, either directly or using a wildcard, thenthe destination must be a directory (must end with a slash/).

COPY accepts a flag--from=<name> that lets you specify the source locationto be a build stage, context, or image. The following example copies files froma stage namedbuild:

FROM golang AS buildWORKDIR /appRUN --mount=type=bind,target=. go build -o /myapp ./cmdCOPY --from=build /myapp /usr/bin/

For more information about copying from named sources, see the--from flag.

Copying from the build context

When copying source files from the build context, paths are interpreted asrelative to the root of the context.

Specifying a source path with a leading slash or one that navigates outside thebuild context, such asCOPY ../something /something, automatically removesany parent directory navigation (../). Trailing slashes in the source pathare also disregarded, makingCOPY something/ /something equivalent toCOPY something /something.

If the source is a directory, the contents of the directory are copied,including filesystem metadata. The directory itself isn't copied, only itscontents. If it contains subdirectories, these are also copied, and merged withany existing directories at the destination. Any conflicts are resolved infavor of the content being added, on a file-by-file basis, except if you'retrying to copy a directory onto an existing file, in which case an error israised.

If the source is a file, the file and its metadata are copied to thedestination. File permissions are preserved. If the source is a file and adirectory with the same name exists at the destination, an error is raised.

If you pass a Dockerfile through stdin to the build (docker build - < Dockerfile), there is no build context. In this case, you can only use theCOPY instruction to copy files from other stages, named contexts, or images,using the--from flag. You can also pass a tar archivethrough stdin: (docker build - < archive.tar), the Dockerfile at the root ofthe archive and the rest of the archive will be used as the context of thebuild.

When using a Git repository as the build context, the permissions bits forcopied files are 644. If a file in the repository has the executable bit set,it will have permissions set to 755. Directories have permissions set to 755.

Pattern matching

For local files, each<src> may contain wildcards and matching will be doneusing Go'sfilepath.Match rules.

For example, to add all files and directories in the root of the build contextending with.png:

COPY *.png /dest/

In the following example,? is a single-character wildcard, matching e.g.index.js andindex.ts.

COPY index.?s /dest/

When adding files or directories that contain special characters (such as[and]), you need to escape those paths following the Golang rules to preventthem from being treated as a matching pattern. For example, to add a filenamedarr[0].txt, use the following;

COPY arr[[]0].txt /dest/

Destination

If the destination path begins with a forward slash, it's interpreted as anabsolute path, and the source files are copied into the specified destinationrelative to the root of the current build stage.

# create /abs/test.txtCOPY test.txt /abs/

Trailing slashes are significant. For example,COPY test.txt /abs creates afile at/abs, whereasCOPY test.txt /abs/ creates/abs/test.txt.

If the destination path doesn't begin with a leading slash, it's interpreted asrelative to the working directory of the build container.

WORKDIR /usr/src/app# create /usr/src/app/rel/test.txtCOPY test.txt rel/

If destination doesn't exist, it's created, along with all missing directoriesin its path.

If the source is a file, and the destination doesn't end with a trailing slash,the source file will be written to the destination path as a file.

COPY --from

By default, theCOPY instruction copies files from the build context. TheCOPY --from flag lets you copy files from an image, a build stage,or a named context instead.

COPY[--from=<image|stage|context>] <src> ... <dest>

To copy from a build stage in amulti-stage build,specify the name of the stage you want to copy from. You specify stage namesusing theAS keyword with theFROM instruction.

# syntax=docker/dockerfile:1FROM alpine AS buildCOPY . .RUN apk add clangRUN clang -o /hello hello.cFROM scratchCOPY --from=build /hello /

You can also copy files directly from named contexts (specified with--build-context <name>=<source>) or images. The following example copies annginx.conf file from the official Nginx image.

COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf

The source path ofCOPY --from is always resolved from filesystem root of theimage or stage that you specify.

COPY --chown --chmod

Note

Only octal notation is currently supported. Non-octal support is tracked inmoby/buildkit#1951.

COPY[--chown=<user>:<group>][--chmod=<perms> ...] <src> ... <dest>

The--chown and--chmod features are only supported on Dockerfiles used to build Linux containers,and doesn't work on Windows containers. Since user and group ownership concepts donot translate between Linux and Windows, the use of/etc/passwd and/etc/group fortranslating user and group names to IDs restricts this feature to only be viable forLinux OS-based containers.

All files and directories copied from the build context are created with a UID and GID of0 unless theoptional--chown flag specifies a given username, groupname, or UID/GIDcombination to request specific ownership of the copied content. Theformat of the--chown flag allows for either username and groupname stringsor direct integer UID and GID in any combination. Providing a username withoutgroupname or a UID without GID will use the same numeric UID as the GID. If ausername or groupname is provided, the container's root filesystem/etc/passwd and/etc/group files will be used to perform the translationfrom name to integer UID or GID respectively. The following examples showvalid definitions for the--chown flag:

COPY --chown=55:mygroup files* /somedir/COPY --chown=bin files* /somedir/COPY --chown=1 files* /somedir/COPY --chown=10:11 files* /somedir/COPY --chown=myuser:mygroup --chmod=644 files* /somedir/

If the container root filesystem doesn't contain either/etc/passwd or/etc/group files and either user or group names are used in the--chownflag, the build will fail on theCOPY operation. Using numeric IDs requiresno lookup and does not depend on container root filesystem content.

With the Dockerfile syntax version 1.10.0 and later,the--chmod flag supports variable interpolation,which lets you define the permission bits using build arguments:

# syntax=docker/dockerfile:1.10FROM alpineWORKDIR /srcARGMODE=440COPY --chmod=$MODE . .

COPY --link

COPY[--link[=<boolean>]] <src> ... <dest>

Enabling this flag inCOPY orADD commands allows you to copy files withenhanced semantics where your files remain independent on their own layer anddon't get invalidated when commands on previous layers are changed.

When--link is used your source files are copied into an empty destinationdirectory. That directory is turned into a layer that is linked on top of yourprevious state.

# syntax=docker/dockerfile:1FROM alpineCOPY --link /foo /bar

Is equivalent of doing two builds:

FROM alpine

and

FROM scratchCOPY /foo /bar

and merging all the layers of both images together.

Benefits of using--link

Use--link to reuse already built layers in subsequent builds with--cache-from even if the previous layers have changed. This is especiallyimportant for multi-stage builds where aCOPY --from statement wouldpreviously get invalidated if any previous commands in the same stage changed,causing the need to rebuild the intermediate stages again. With--link thelayer the previous build generated is reused and merged on top of the newlayers. This also means you can easily rebase your images when the base imagesreceive updates, without having to execute the whole build again. In backendsthat support it, BuildKit can do this rebase action without the need to push orpull any layers between the client and the registry. BuildKit will detect thiscase and only create new image manifest that contains the new layers and oldlayers in correct order.

The same behavior where BuildKit can avoid pulling down the base image can alsohappen when using--link and no other commands that would require access tothe files in the base image. In that case BuildKit will only build the layersfor theCOPY commands and push them to the registry directly on top of thelayers of the base image.

Incompatibilities with--link=false

When using--link theCOPY/ADD commands are not allowed to read any filesfrom the previous state. This means that if in previous state the destinationdirectory was a path that contained a symlink,COPY/ADD can not follow it.In the final image the destination path created with--link will always be apath containing only directories.

If you don't rely on the behavior of following symlinks in the destinationpath, using--link is always recommended. The performance of--link isequivalent or better than the default behavior and, it creates much betterconditions for cache reuse.

COPY --parents

Note

Not yet available in stable syntax, usedocker/dockerfile:1.7-labs version.

COPY[--parents[=<boolean>]] <src> ... <dest>

The--parents flag preserves parent directories forsrc entries. This flag defaults tofalse.

# syntax=docker/dockerfile:1-labsFROM scratchCOPY ./x/a.txt ./y/a.txt /no_parents/COPY --parents ./x/a.txt ./y/a.txt /parents/# /no_parents/a.txt# /parents/x/a.txt# /parents/y/a.txt

This behavior is similar to theLinuxcp utility's--parents orrsync--relative flag.

As with Rsync, it is possible to limit which parent directories are preserved byinserting a dot and a slash (./) into the source path. If such point exists, only parentdirectories after it will be preserved. This may be especially useful copies between stageswith--from where the source paths need to be absolute.

# syntax=docker/dockerfile:1-labsFROM scratchCOPY --parents ./x/./y/*.txt /parents/# Build context:# ./x/y/a.txt# ./x/y/b.txt## Output:# /parents/y/a.txt# /parents/y/b.txt

Note that, without the--parents flag specified, any filename collision willfail the Linuxcp operation with an explicit error message(cp: will not overwrite just-created './x/a.txt' with './y/a.txt'), where theBuildkit will silently overwrite the target file at the destination.

While it is possible to preserve the directory structure forCOPYinstructions consisting of only onesrc entry, usually it is more beneficialto keep the layer count in the resulting image as low as possible. Therefore,with the--parents flag, the Buildkit is capable of packing multipleCOPY instructions together, keeping the directory structure intact.

COPY --exclude

Note

Not yet available in stable syntax, usedocker/dockerfile:1.7-labs version.

COPY[--exclude=<path> ...] <src> ... <dest>

The--exclude flag lets you specify a path expression for files to be excluded.

The path expression follows the same format as<src>,supporting wildcards and matching using Go'sfilepath.Match rules.For example, to add all files starting with "hom", excluding files with a.txt extension:

# syntax=docker/dockerfile:1-labsFROM scratchCOPY --exclude=*.txt hom* /mydir/

You can specify the--exclude option multiple times for aCOPY instruction.Multiple--excludes are files matching its patterns not to be copied,even if the files paths match the pattern specified in<src>.To add all files starting with "hom", excluding files with either.txt or.md extensions:

# syntax=docker/dockerfile:1-labsFROM scratchCOPY --exclude=*.txt --exclude=*.md hom* /mydir/

ENTRYPOINT

AnENTRYPOINT allows you to configure a container that will run as an executable.

ENTRYPOINT has two possible forms:

• The exec form, which is the preferred form:

  ENTRYPOINT["executable","param1","param2"]

• The shell form:

  ENTRYPOINTcommand param1 param2

For more information about the different forms, seeShell and exec form.

The following command starts a container from thenginx with its defaultcontent, listening on port 80:

$ docker run -i -t --rm -p 80:80 nginx

Command line arguments todocker run <image> will be appended after allelements in an exec formENTRYPOINT, and will override all elements specifiedusingCMD.

This allows arguments to be passed to the entry point, i.e.,docker run <image> -d will pass the-d argument to the entry point. You can overridetheENTRYPOINT instruction using thedocker run --entrypoint flag.

The shell form ofENTRYPOINT prevents anyCMD command line arguments frombeing used. It also starts yourENTRYPOINT as a subcommand of/bin/sh -c,which does not pass signals. This means that the executable will not be thecontainer'sPID 1, and will not receive Unix signals. In this case, yourexecutable doesn't receive aSIGTERM fromdocker stop <container>.

Only the lastENTRYPOINT instruction in the Dockerfile will have an effect.

Exec form ENTRYPOINT example

You can use the exec form ofENTRYPOINT to set fairly stable default commandsand arguments and then use either form ofCMD to set additional defaults thatare more likely to be changed.

FROM ubuntuENTRYPOINT["top","-b"]CMD["-c"]

When you run the container, you can see thattop is the only process:

$ docker run -it --rm --nametest  top -Htop - 08:25:00 up  7:27,  0 users,  load average: 0.00, 0.01, 0.05Threads:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie%Cpu(s):  0.1 us,  0.1 sy,  0.0 ni, 99.7 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 stKiB Mem:   2056668 total,  1616832 used,   439836 free,    99352 buffersKiB Swap:  1441840 total,        0 used,  1441840 free.  1324440 cached Mem  PID USER      PR  NI    VIRT    RES    SHR S %CPU %MEM     TIME+ COMMAND    1 root      20   0   19744   2336   2080 R  0.0  0.1   0:00.04 top

To examine the result further, you can usedocker exec:

$ dockerexec -ittest ps auxUSER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMANDroot         1  2.6  0.1  19752  2352 ?        Ss+  08:24   0:00 top -b -Hroot         7  0.0  0.1  15572  2164 ?        R+   08:25   0:00 ps aux

And you can gracefully requesttop to shut down usingdocker stop test.

The following Dockerfile shows using theENTRYPOINT to run Apache in theforeground (i.e., asPID 1):

FROM debian:stableRUN apt-get update&& apt-get install -y --force-yes apache2EXPOSE 80 443VOLUME["/var/www","/var/log/apache2","/etc/apache2"]ENTRYPOINT["/usr/sbin/apache2ctl","-D","FOREGROUND"]

If you need to write a starter script for a single executable, you can ensure thatthe final executable receives the Unix signals by usingexec andgosucommands:

#!/usr/bin/env bashset -eif["$1"='postgres'];then    chown -R postgres"$PGDATA"if[ -z"$(ls -A"$PGDATA")"];then        gosu postgres initdbfiexec gosu postgres"$@"fiexec"$@"

Lastly, if you need to do some extra cleanup (or communicate with other containers)on shutdown, or are co-ordinating more than one executable, you may need to ensurethat theENTRYPOINT script receives the Unix signals, passes them on, and thendoes some more work:

#!/bin/sh# Note: I've written this using sh so it works in the busybox container too# USE the trap if you need to also do manual cleanup after the service is stopped,#     or need to start multiple services in the one containertrap"echo TRAPed signal" HUP INT QUIT TERM# start service in background here/usr/sbin/apachectl startecho"[hit enter key to exit] or run 'docker stop <container>'"read# stop service and clean up hereecho"stopping apache"/usr/sbin/apachectl stopecho"exited$0"

If you run this image withdocker run -it --rm -p 80:80 --name test apache,you can then examine the container's processes withdocker exec, ordocker top,and then ask the script to stop Apache:

$ dockerexec -ittest ps auxUSER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMANDroot         1  0.1  0.0   4448   692 ?        Ss+  00:42   0:00 /bin/sh /run.sh 123 cmd cmd2root        19  0.0  0.2  71304  4440 ?        Ss   00:42   0:00 /usr/sbin/apache2 -k startwww-data    20  0.2  0.2 360468  6004 ?        Sl   00:42   0:00 /usr/sbin/apache2 -k startwww-data    21  0.2  0.2 360468  6000 ?        Sl   00:42   0:00 /usr/sbin/apache2 -k startroot        81  0.0  0.1  15572  2140 ?        R+   00:44   0:00 ps aux$ docker toptestPID                 USER                COMMAND10035               root                {run.sh} /bin/sh /run.sh 123 cmd cmd210054               root                /usr/sbin/apache2 -k start10055               33                  /usr/sbin/apache2 -k start10056               33                  /usr/sbin/apache2 -k start$ /usr/bin/time docker stoptesttestreal0m 0.27suser0m 0.03ssys0m 0.03s

Note

You can override theENTRYPOINT setting using--entrypoint,but this can only set the binary to exec (nosh -c will be used).

Shell form ENTRYPOINT example

You can specify a plain string for theENTRYPOINT and it will execute in/bin/sh -c.This form will use shell processing to substitute shell environment variables,and will ignore anyCMD ordocker run command line arguments.To ensure thatdocker stop will signal any long runningENTRYPOINT executablecorrectly, you need to remember to start it withexec:

FROM ubuntuENTRYPOINTexec top -b

When you run this image, you'll see the singlePID 1 process:

$ docker run -it --rm --nametest topMem: 1704520K used, 352148K free, 0K shrd, 0K buff, 140368121167873K cachedCPU:   5% usr   0% sys   0% nic  94% idle   0% io   0% irq   0% sirqLoad average: 0.08 0.03 0.05 2/98 6  PID  PPID USER     STAT   VSZ %VSZ %CPU COMMAND    1     0 root     R     3164   0%   0% top -b

Which exits cleanly ondocker stop:

$ /usr/bin/time docker stoptesttestreal0m 0.20suser0m 0.02ssys0m 0.04s

If you forget to addexec to the beginning of yourENTRYPOINT:

FROM ubuntuENTRYPOINT top -bCMD -- --ignored-param1

You can then run it (giving it a name for the next step):

$ docker run -it --nametest top --ignored-param2top - 13:58:24 up 17 min,  0 users,  load average: 0.00, 0.00, 0.00Tasks:   2 total,   1 running,   1 sleeping,   0 stopped,   0 zombie%Cpu(s): 16.7 us, 33.3 sy,  0.0 ni, 50.0 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 stMiB Mem :   1990.8 total,   1354.6 free,    231.4 used,    404.7 buff/cacheMiB Swap:   1024.0 total,   1024.0 free,      0.0 used.   1639.8 avail Mem  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND    1 root      20   0    2612    604    536 S   0.0   0.0   0:00.02 sh    6 root      20   0    5956   3188   2768 R   0.0   0.2   0:00.00 top

You can see from the output oftop that the specifiedENTRYPOINT is notPID 1.

If you then rundocker stop test, the container will not exit cleanly - thestop command will be forced to send aSIGKILL after the timeout:

$ dockerexec -ittest ps wauxUSER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMANDroot         1  0.4  0.0   2612   604 pts/0    Ss+  13:58   0:00 /bin/sh -c top -b --ignored-param2root         6  0.0  0.1   5956  3188 pts/0    S+   13:58   0:00 top -broot         7  0.0  0.1   5884  2816 pts/1    Rs+  13:58   0:00 ps waux$ /usr/bin/time docker stoptesttestreal0m 10.19suser0m 0.04ssys0m 0.03s

Understand how CMD and ENTRYPOINT interact

BothCMD andENTRYPOINT instructions define what command gets executed when running a container.There are few rules that describe their co-operation.

1. Dockerfile should specify at least one ofCMD orENTRYPOINT commands.

2. ENTRYPOINT should be defined when using the container as an executable.

3. CMD should be used as a way of defining default arguments for anENTRYPOINT commandor for executing an ad-hoc command in a container.

4. CMD will be overridden when running the container with alternative arguments.

The table below shows what command is executed for differentENTRYPOINT /CMD combinations:

Note

IfCMD is defined from the base image, settingENTRYPOINT willresetCMD to an empty value. In this scenario,CMD must be defined in thecurrent image to have a value.

VOLUME

VOLUME["/data"]

TheVOLUME instruction creates a mount point with the specified nameand marks it as holding externally mounted volumes from native host or othercontainers. The value can be a JSON array,VOLUME ["/var/log/"], or a plainstring with multiple arguments, such asVOLUME /var/log orVOLUME /var/log /var/db. For more information/examples and mounting instructions via theDocker client, refer toShare Directories via Volumesdocumentation.

Thedocker run command initializes the newly created volume with any datathat exists at the specified location within the base image. For example,consider the following Dockerfile snippet:

FROM ubuntuRUN mkdir /myvolRUNecho"hello world" > /myvol/greetingVOLUME /myvol

This Dockerfile results in an image that causesdocker run tocreate a new mount point at/myvol and copy thegreeting fileinto the newly created volume.

Notes about specifying volumes

Keep the following things in mind about volumes in the Dockerfile.

• Volumes on Windows-based containers: When using Windows-based containers,the destination of a volume inside the container must be one of:

  • a non-existing or empty directory
  • a drive other thanC:

• Changing the volume from within the Dockerfile: If any build steps change thedata within the volume after it has been declared, those changes will be discardedwhen using the legacy builder. When using Buildkit, the changes will instead be kept.

• JSON formatting: The list is parsed as a JSON array.You must enclose words with double quotes (") rather than single quotes (').

• The host directory is declared at container run-time: The host directory(the mountpoint) is, by its nature, host-dependent. This is to preserve imageportability, since a given host directory can't be guaranteed to be availableon all hosts. For this reason, you can't mount a host directory fromwithin the Dockerfile. TheVOLUME instruction does not support specifying ahost-dirparameter. You must specify the mountpoint when you create or run the container.

USER

USER <user>[:<group>]

or

USER <UID>[:<GID>]

TheUSER instruction sets the user name (or UID) and optionally the usergroup (or GID) to use as the default user and group for the remainder of thecurrent stage. The specified user is used forRUN instructions and atruntime, runs the relevantENTRYPOINT andCMD commands.

Note that when specifying a group for the user, the user will haveonly thespecified group membership. Any other configured group memberships will be ignored.

Warning

When the user doesn't have a primary group then the image (or the nextinstructions) will be run with theroot group.

On Windows, the user must be created first if it's not a built-in account.This can be done with thenet user command called as part of a Dockerfile.

FROM microsoft/windowsservercore# Create Windows user in the containerRUN net user /add patrick# Set it for subsequent commandsUSER patrick

WORKDIR

WORKDIR /path/to/workdir

TheWORKDIR instruction sets the working directory for anyRUN,CMD,ENTRYPOINT,COPY andADD instructions that follow it in the Dockerfile.If theWORKDIR doesn't exist, it will be created even if it's not used in anysubsequent Dockerfile instruction.

TheWORKDIR instruction can be used multiple times in a Dockerfile. If arelative path is provided, it will be relative to the path of the previousWORKDIR instruction. For example:

WORKDIR /aWORKDIR bWORKDIR cRUN pwd

The output of the finalpwd command in this Dockerfile would be/a/b/c.

TheWORKDIR instruction can resolve environment variables previously set usingENV. You can only use environment variables explicitly set in the Dockerfile.For example:

ENVDIRPATH=/pathWORKDIR $DIRPATH/$DIRNAMERUN pwd

The output of the finalpwd command in this Dockerfile would be/path/$DIRNAME

If not specified, the default working directory is/. In practice, if you aren't building a Dockerfile from scratch (FROM scratch),theWORKDIR may likely be set by the base image you're using.

Therefore, to avoid unintended operations in unknown directories, it's best practice to set yourWORKDIR explicitly.

ARG

ARG <name>[=<default value>][<name>[=<default value>]...]

TheARG instruction defines a variable that users can pass at build-time tothe builder with thedocker build command using the--build-arg <varname>=<value>flag.

Warning

It isn't recommended to use build arguments for passing secrets such asuser credentials, API tokens, etc. Build arguments are visible in thedocker history command and inmax mode provenance attestations,which are attached to the image by default if you use the Buildx GitHub Actionsand your GitHub repository is public.

Refer to theRUN --mount=type=secret section tolearn about secure ways to use secrets when building images.

A Dockerfile may include one or moreARG instructions. For example,the following is a valid Dockerfile:

FROM busyboxARG user1ARG buildno# ...

Default values

AnARG instruction can optionally include a default value:

FROM busyboxARGuser1=someuserARGbuildno=1# ...

If anARG instruction has a default value and if there is no value passedat build-time, the builder uses the default.

Scope

AnARG variable comes into effect from the line on which it is declared inthe Dockerfile. For example, consider this Dockerfile:

FROM busyboxUSER ${username:-some_user}ARG usernameUSER $username# ...

A user builds this file by calling:

$ docker build --build-argusername=what_user .

• TheUSER instruction on line 2 evaluates to thesome_user fallback,because theusername variable is not yet declared.
• Theusername variable is declared on line 3, and available for reference inDockerfile instruction from that point onwards.
• TheUSER instruction on line 4 evaluates towhat_user, since at thatpoint theusername argument has a value ofwhat_user which was passed onthe command line. Prior to its definition by anARG instruction, any use ofa variable results in an empty string.

AnARG variable declared within a build stage is automatically inherited byother stages based on that stage. Unrelated build stages do not have access tothe variable. To use an argument in multiple distinct stages, each stage mustinclude theARG instruction, or they must both be based on a shared basestage in the same Dockerfile where the variable is declared.

For more information, refer tovariable scoping.

Using ARG variables

You can use anARG or anENV instruction to specify variables that areavailable to theRUN instruction. Environment variables defined using theENV instruction always override anARG instruction of the same name. Considerthis Dockerfile with anENV andARG instruction.

FROM ubuntuARG CONT_IMG_VERENVCONT_IMG_VER=v1.0.0RUNecho$CONT_IMG_VER

Then, assume this image is built with this command:

$ docker build --build-argCONT_IMG_VER=v2.0.1 .

In this case, theRUN instruction usesv1.0.0 instead of theARG settingpassed by the user:v2.0.1 This behavior is similar to a shellscript where a locally scoped variable overrides the variables passed asarguments or inherited from environment, from its point of definition.

Using the example above but a differentENV specification you can create moreuseful interactions betweenARG andENV instructions:

FROM ubuntuARG CONT_IMG_VERENVCONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}RUNecho$CONT_IMG_VER

Unlike anARG instruction,ENV values are always persisted in the builtimage. Consider a docker build without the--build-arg flag:

$ docker build .

Using this Dockerfile example,CONT_IMG_VER is still persisted in the image butits value would bev1.0.0 as it is the default set in line 3 by theENV instruction.

The variable expansion technique in this example allows you to pass argumentsfrom the command line and persist them in the final image by leveraging theENV instruction. Variable expansion is only supported fora limited set ofDockerfile instructions.

Predefined ARGs

Docker has a set of predefinedARG variables that you can use without acorrespondingARG instruction in the Dockerfile.

• HTTP_PROXY
• http_proxy
• HTTPS_PROXY
• https_proxy
• FTP_PROXY
• ftp_proxy
• NO_PROXY
• no_proxy
• ALL_PROXY
• all_proxy

To use these, pass them on the command line using the--build-arg flag, forexample:

$ docker build --build-argHTTPS_PROXY=https://my-proxy.example.com .

By default, these pre-defined variables are excluded from the output ofdocker history. Excluding them reduces the risk of accidentally leakingsensitive authentication information in anHTTP_PROXY variable.

For example, consider building the following Dockerfile using--build-arg HTTP_PROXY=http://user:pass@proxy.lon.example.com

FROM ubuntuRUNecho"Hello World"

In this case, the value of theHTTP_PROXY variable is not available in thedocker history and is not cached. If you were to change location, and yourproxy server changed tohttp://user:pass@proxy.sfo.example.com, a subsequentbuild does not result in a cache miss.

If you need to override this behaviour then you may do so by adding anARGstatement in the Dockerfile as follows:

FROM ubuntuARG HTTP_PROXYRUNecho"Hello World"

When building this Dockerfile, theHTTP_PROXY is preserved in thedocker history, and changing its value invalidates the build cache.

Automatic platform ARGs in the global scope

This feature is only available when using theBuildKitbackend.

BuildKit supports a predefined set ofARG variables with information on the platform ofthe node performing the build (build platform) and on the platform of theresulting image (target platform). The target platform can be specified withthe--platform flag ondocker build.

The followingARG variables are set automatically:

• TARGETPLATFORM - platform of the build result. Eglinux/amd64,linux/arm/v7,windows/amd64.
• TARGETOS - OS component of TARGETPLATFORM
• TARGETARCH - architecture component of TARGETPLATFORM
• TARGETVARIANT - variant component of TARGETPLATFORM
• BUILDPLATFORM - platform of the node performing the build.
• BUILDOS - OS component of BUILDPLATFORM
• BUILDARCH - architecture component of BUILDPLATFORM
• BUILDVARIANT - variant component of BUILDPLATFORM

These arguments are defined in the global scope so are not automaticallyavailable inside build stages or for yourRUN commands. To expose one ofthese arguments inside the build stage redefine it without value.

For example:

FROM alpineARG TARGETPLATFORMRUNecho"I'm building for$TARGETPLATFORM"

BuildKit built-in build args

Example: keep.git dir

When using a Git context,.git dir is not kept on checkouts. It can beuseful to keep it around if you want to retrieve git information duringyour build:

# syntax=docker/dockerfile:1FROM alpineWORKDIR /srcRUN --mount=target=.\  makeREVISION=$(git rev-parse HEAD) build

$ docker build --build-argBUILDKIT_CONTEXT_KEEP_GIT_DIR=1 https://github.com/user/repo.git#main

Impact on build caching

ARG variables are not persisted into the built image asENV variables are.However,ARG variables do impact the build cache in similar ways. If aDockerfile defines anARG variable whose value is different from a previousbuild, then a "cache miss" occurs upon its first usage, not its definition. Inparticular, allRUN instructions following anARG instruction use theARGvariable implicitly (as an environment variable), thus can cause a cache miss.All predefinedARG variables are exempt from caching unless there is amatchingARG statement in the Dockerfile.

For example, consider these two Dockerfile:

FROM ubuntuARG CONT_IMG_VERRUNecho$CONT_IMG_VER

FROM ubuntuARG CONT_IMG_VERRUNecho hello

If you specify--build-arg CONT_IMG_VER=<value> on the command line, in bothcases, the specification on line 2 doesn't cause a cache miss; line 3 doescause a cache miss.ARG CONT_IMG_VER causes theRUN line to be identifiedas the same as runningCONT_IMG_VER=<value> echo hello, so if the<value>changes, you get a cache miss.

Consider another example under the same command line:

FROM ubuntuARG CONT_IMG_VERENVCONT_IMG_VER=$CONT_IMG_VERRUNecho$CONT_IMG_VER

In this example, the cache miss occurs on line 3. The miss happens becausethe variable's value in theENV references theARG variable and thatvariable is changed through the command line. In this example, theENVcommand causes the image to include the value.

If anENV instruction overrides anARG instruction of the same name, likethis Dockerfile:

FROM ubuntuARG CONT_IMG_VERENVCONT_IMG_VER=helloRUNecho$CONT_IMG_VER

Line 3 doesn't cause a cache miss because the value ofCONT_IMG_VER is aconstant (hello). As a result, the environment variables and values used ontheRUN (line 4) doesn't change between builds.

ONBUILD

ONBUILD <INSTRUCTION>

TheONBUILD instruction adds to the image a trigger instruction tobe executed at a later time, when the image is used as the base foranother build. The trigger will be executed in the context of thedownstream build, as if it had been inserted immediately after theFROM instruction in the downstream Dockerfile.

This is useful if you are building an image which will be used as a baseto build other images, for example an application build environment or adaemon which may be customized with user-specific configuration.

For example, if your image is a reusable Python application builder, itwill require application source code to be added in a particulardirectory, and it might require a build script to be called afterthat. You can't just callADD andRUN now, because you don't yethave access to the application source code, and it will be different foreach application build. You could simply provide application developerswith a boilerplate Dockerfile to copy-paste into their application, butthat's inefficient, error-prone and difficult to update because itmixes with application-specific code.

The solution is to useONBUILD to register advance instructions torun later, during the next build stage.

Here's how it works:

1. When it encounters anONBUILD instruction, the builder adds atrigger to the metadata of the image being built. The instructiondoesn't otherwise affect the current build.
2. At the end of the build, a list of all triggers is stored in theimage manifest, under the keyOnBuild. They can be inspected withthedocker inspect command.
3. Later the image may be used as a base for a new build, using theFROM instruction. As part of processing theFROM instruction,the downstream builder looks forONBUILD triggers, and executesthem in the same order they were registered. If any of the triggersfail, theFROM instruction is aborted which in turn causes thebuild to fail. If all triggers succeed, theFROM instructioncompletes and the build continues as usual.
4. Triggers are cleared from the final image after being executed. Inother words they aren't inherited by "grand-children" builds.

For example you might add something like this:

ONBUILDADD . /app/srcONBUILDRUN /usr/local/bin/python-build --dir /app/src

Copy or mount from stage, image, or context

As of Dockerfile syntax 1.11, you can useONBUILD with instructions that copyor mount files from other stages, images, or build contexts. For example:

# syntax=docker/dockerfile:1.11FROM alpine AS baseimageONBUILDCOPY --from=build /usr/bin/app /appONBUILDRUN --mount=from=config,target=/opt/appconfig ...

If the source offrom is a build stage, the stage must be defined in theDockerfile whereONBUILD gets triggered. If it's a named context, thatcontext must be passed to the downstream build.

ONBUILD limitations

• ChainingONBUILD instructions usingONBUILD ONBUILD isn't allowed.
• TheONBUILD instruction may not triggerFROM orMAINTAINER instructions.

STOPSIGNAL

STOPSIGNAL signal

TheSTOPSIGNAL instruction sets the system call signal that will be sent to thecontainer to exit. This signal can be a signal name in the formatSIG<NAME>,for instanceSIGKILL, or an unsigned number that matches a position in thekernel's syscall table, for instance9. The default isSIGTERM if notdefined.

The image's default stopsignal can be overridden per container, using the--stop-signal flag ondocker run anddocker create.

HEALTHCHECK

TheHEALTHCHECK instruction has two forms:

• HEALTHCHECK [OPTIONS] CMD command (check container health by running a command inside the container)
• HEALTHCHECK NONE (disable any healthcheck inherited from the base image)

TheHEALTHCHECK instruction tells Docker how to test a container to check thatit's still working. This can detect cases such as a web server stuck inan infinite loop and unable to handle new connections, even though the serverprocess is still running.

When a container has a healthcheck specified, it has a health status inaddition to its normal status. This status is initiallystarting. Whenever ahealth check passes, it becomeshealthy (whatever state it was previously in).After a certain number of consecutive failures, it becomesunhealthy.

The options that can appear beforeCMD are:

• --interval=DURATION (default:30s)
• --timeout=DURATION (default:30s)
• --start-period=DURATION (default:0s)
• --start-interval=DURATION (default:5s)
• --retries=N (default:3)

The health check will first runinterval seconds after the container isstarted, and then againinterval seconds after each previous check completes.

If a single run of the check takes longer thantimeout seconds then the checkis considered to have failed.

It takesretries consecutive failures of the health check for the containerto be consideredunhealthy.

start period provides initialization time for containers that need time to bootstrap.Probe failure during that period will not be counted towards the maximum number of retries.However, if a health check succeeds during the start period, the container is consideredstarted and all consecutive failures will be counted towards the maximum number of retries.

start interval is the time between health checks during the start period.This option requires Docker Engine version 25.0 or later.

There can only be oneHEALTHCHECK instruction in a Dockerfile. If you listmore than one then only the lastHEALTHCHECK will take effect.

The command after theCMD keyword can be either a shell command (e.g.HEALTHCHECK CMD /bin/check-running) or an exec array (as with other Dockerfile commands;see e.g.ENTRYPOINT for details).

The command's exit status indicates the health status of the container.The possible values are:

• 0: success - the container is healthy and ready for use
• 1: unhealthy - the container isn't working correctly
• 2: reserved - don't use this exit code

For example, to check every five minutes or so that a web-server is able toserve the site's main page within three seconds:

HEALTHCHECK --interval=5m --timeout=3s \CMD curl -f http://localhost/||exit1

To help debug failing probes, any output text (UTF-8 encoded) that the command writeson stdout or stderr will be stored in the health status and can be queried withdocker inspect. Such output should be kept short (only the first 4096 bytesare stored currently).

When the health status of a container changes, ahealth_status event isgenerated with the new status.

SHELL

SHELL["executable","parameters"]

TheSHELL instruction allows the default shell used for the shell form ofcommands to be overridden. The default shell on Linux is["/bin/sh", "-c"], and onWindows is["cmd", "/S", "/C"]. TheSHELL instruction must be written in JSONform in a Dockerfile.

TheSHELL instruction is particularly useful on Windows where there aretwo commonly used and quite different native shells:cmd andpowershell, aswell as alternate shells available includingsh.

TheSHELL instruction can appear multiple times. EachSHELL instruction overridesall previousSHELL instructions, and affects all subsequent instructions. For example:

FROM microsoft/windowsservercore# Executed as cmd /S /C echo defaultRUNecho default# Executed as cmd /S /C powershell -command Write-Host defaultRUN powershell -command Write-Host default# Executed as powershell -command Write-Host helloSHELL["powershell","-command"]RUN Write-Host hello# Executed as cmd /S /C echo helloSHELL["cmd","/S","/C"]RUNecho hello

The following instructions can be affected by theSHELL instruction when theshell form of them is used in a Dockerfile:RUN,CMD andENTRYPOINT.

The following example is a common pattern found on Windows which can bestreamlined by using theSHELL instruction:

RUN powershell -command Execute-MyCmdlet -param1"c:\foo.txt"

The command invoked by the builder will be:

cmd/S/Cpowershell-commandExecute-MyCmdlet-param1"c:\foo.txt"

This is inefficient for two reasons. First, there is an unnecessarycmd.execommand processor (aka shell) being invoked. Second, eachRUN instruction inthe shell form requires an extrapowershell -command prefixing the command.

To make this more efficient, one of two mechanisms can be employed. One is touse the JSON form of theRUN command such as:

RUN["powershell","-command","Execute-MyCmdlet","-param1 \"c:\\foo.txt\""]

While the JSON form is unambiguous and does not use the unnecessarycmd.exe,it does require more verbosity through double-quoting and escaping. The alternatemechanism is to use theSHELL instruction and the shell form,making a more natural syntax for Windows users, especially when combined withtheescape parser directive:

# escape=`FROM microsoft/nanoserverSHELL["powershell","-command"]RUN New-Item -ItemType Directory C:\ExampleADD Execute-MyCmdlet.ps1 c:\example\RUN c:\example\Execute-MyCmdlet -sample'hello world'

Resulting in:

PS E:\myproject> docker build -t shell .Sending build context to Docker daemon 4.096 kBStep 1/5 : FROM microsoft/nanoserver ---> 22738ff49c6dStep 2/5 : SHELL powershell -command ---> Running in 6fcdb6855ae2 ---> 6331462d4300Removing intermediate container 6fcdb6855ae2Step 3/5 : RUN New-Item -ItemType Directory C:\Example ---> Running in d0eef8386e97    Directory: C:\Mode         LastWriteTime              Length Name----         -------------              ------ ----d-----       10/28/2016  11:26 AM              Example ---> 3f2fbf1395d9Removing intermediate container d0eef8386e97Step 4/5 : ADD Execute-MyCmdlet.ps1 c:\example\ ---> a955b2621c31Removing intermediate container b825593d39fcStep 5/5 : RUN c:\example\Execute-MyCmdlet 'hello world' ---> Running in be6d8e63fe75hello world ---> 8e559e9bf424Removing intermediate container be6d8e63fe75Successfully built 8e559e9bf424PS E:\myproject>

TheSHELL instruction could also be used to modify the way in whicha shell operates. For example, usingSHELL cmd /S /C /V:ON|OFF on Windows, delayedenvironment variable expansion semantics could be modified.

TheSHELL instruction can also be used on Linux should an alternate shell berequired such aszsh,csh,tcsh and others.

Here-Documents

Here-documents allow redirection of subsequent Dockerfile lines to the input ofRUN orCOPY commands. If such command contains ahere-documentthe Dockerfile considers the next lines until the line only containing ahere-doc delimiter as part of the same command.

Example: Running a multi-line script

# syntax=docker/dockerfile:1FROM debianRUN <<EOT bashset -ex  apt-get update  apt-get install -y vimEOT

If the command only contains a here-document, its contents is evaluated withthe default shell.

# syntax=docker/dockerfile:1FROM debianRUN <<EOT  mkdir -p foo/barEOT

Alternatively, shebang header can be used to define an interpreter.

# syntax=docker/dockerfile:1FROM python:3.6RUN <<EOT#!/usr/bin/env pythonprint("hello world")EOT

More complex examples may use multiple here-documents.

# syntax=docker/dockerfile:1FROM alpineRUN<<FILE1 cat > file1 && <<FILE2 cat > file2I amfirstFILE1I amsecondFILE2

Example: Creating inline files

WithCOPY instructions, you can replace the source parameter with a here-docindicator to write the contents of the here-document directly to a file. Thefollowing example creates agreeting.txt file containinghello world usingaCOPY instruction.

# syntax=docker/dockerfile:1FROM alpineCOPY <<EOF greeting.txthello worldEOF

Regular here-docvariable expansion and tab stripping rules apply.The following example shows a small Dockerfile that creates ahello.sh scriptfile using aCOPY instruction with a here-document.

# syntax=docker/dockerfile:1FROM alpineARGFOO=barCOPY <<-EOT /script.shecho"hello${FOO}"EOTENTRYPOINT ash /script.sh

In this case, file script prints "hello bar", because the variable is expandedwhen theCOPY instruction gets executed.

$ docker build -t heredoc .$ docker run heredochello bar

If instead you were to quote any part of the here-document wordEOT, thevariable would not be expanded at build-time.

# syntax=docker/dockerfile:1FROM alpineARGFOO=barCOPY <<-"EOT" /script.shecho"hello${FOO}"EOTENTRYPOINT ash /script.sh

Note thatARG FOO=bar is excessive here, and can be removed. The variablegets interpreted at runtime, when the script is invoked:

$ docker build -t heredoc .$ docker run -eFOO=world heredochello world