Dockerfile release notes (original) (raw)

This page contains information about the new features, improvements, known issues, and bug fixes inDockerfile reference.

For usage, see theDockerfile frontend syntax page.

2025-04-15

The full release note for this release is availableon GitHub.

• Build error for invalid target now shows suggestions for correct possible names.moby/buildkit#5851
• Fix SBOM attestation producing error for Windows targets.moby/buildkit#5837
• Fix recursive ARG producing an infinite loop when processing an outline request.moby/buildkit#5823
• Fix parsing syntax directive from JSON that would fail if the JSON had other datatypes than strings.moby/buildkit#5815
• Fix platform in image config being in unnormalized form (regression from 1.12).moby/buildkit#5776
• Fix copying into destination directory when directory is not present with WCOW.moby/buildkit#5249 2025-03-05

The full release note for this release is availableon GitHub.

• Normalize platform in image config.moby/buildkit#5776 2025-02-19

The full release note for this release is availableon GitHub.

• COPY --chmod now allows non-octal values. This feature was previously in the labs channel and is now available in the main release.moby/buildkit#5734
• Fix handling of OSVersion platform property if one is set by the base imagemoby/buildkit#5714
• Fix errors where a named context metadata could be resolved even if it was not reachable by the current build configuration, leading to build errorsmoby/buildkit#5688 2025-02-19

Important

The labs channel gives you access to experimental Dockerfile features not yet available in the stable channel.

The full release note for this release is availableon GitHub.

• New RUN --device=name,[required] flag lets builds request CDI devices are available to the build step. Requires BuildKit v0.20.0+moby/buildkit#4056,moby/buildkit#5738 2025-01-20

The full release note for this release is availableon GitHub.

• New TARGETOSVERSION, BUILDOSVERSION builtin build-args are available for Windows builds, and TARGETPLATFORM value now also contains OSVersion value.moby/buildkit#5614
• Allow syntax forwarding for external frontends for files starting with a Byte Order Mark (BOM).moby/buildkit#5645
• Default PATH in Windows Containers has been updated with powershell.exe directory.moby/buildkit#5446
• Fix Dockerfile directive parsing to not allow invalid syntax.moby/buildkit#5646
• Fix case where ONBUILD command may have run twice on inherited stage.moby/buildkit#5593
• Fix possible missing named context replacement for child stages in Dockerfile.moby/buildkit#5596 2025-01-20

Important

The labs channel gives you access to experimental Dockerfile features not yet available in the stable channel.

The full release note for this release is availableon GitHub.

• Fix support for non-octal values for COPY --chmod.moby/buildkit#5626 2024-11-27

The full release note for this release is availableon GitHub.

• Fix incorrect description in History line of image configuration with multiple ARG instructions.moby/buildkit#5508 2024-11-08

The full release note for this release is availableon GitHub.

• Fix regression when using the ONBUILD instruction in stages inherited within the same Dockerfile.moby/buildkit#5490 2024-10-30

The full release note for this release is availableon GitHub.

• TheONBUILD instruction now supports commands that refer to other stages or images with from, such as COPY --from or RUN mount=from=....moby/buildkit#5357
• TheSecretsUsedInArgOrEnv build check has been improved to reduce false positives.moby/buildkit#5208
• A newInvalidDefinitionDescription build check recommends formatting comments for build arguments and stages descriptions. This is anexperimental check.moby/buildkit#5208,moby/buildkit#5414
• Multiple fixes for the ONBUILD instruction's progress and error handling.moby/buildkit#5397
• Improved error reporting for missing flag errors.moby/buildkit#5369
• Enhanced progress output for secret values mounted as environment variables.moby/buildkit#5336
• Added built-in build argument TARGETSTAGE to expose the name of the (final) target stage for the current build.moby/buildkit#5431

Important

The labs channel gives you access to experimental Dockerfile features not yet available in the stable channel.

• COPY --chmod now supports non-octal values.moby/buildkit#5380 2024-09-10

The full release note for this release is availableon GitHub.

• Build secrets can now be mounted as environment variables using the env=VARIABLE option.moby/buildkit#5215
• The# check directive now allows new experimental attribute for enabling experimental validation rules like CopyIgnoredFile.moby/buildkit#5213
• Improve validation of unsupported modifiers for variable substitution.moby/buildkit#5146
• ADD and COPY instructions now support variable interpolation for build arguments for the --chmod option values.moby/buildkit#5151
• Improve validation of the --chmod option for COPY and ADD instructions.moby/buildkit#5148
• Fix missing completions for size and destination attributes on mounts.moby/buildkit#5245
• OCI annotations are now set to the Dockerfile frontend release image.moby/buildkit#5197 2024-07-11

The full release note for this release is availableon GitHub.

• Add new validation rules:
  • SecretsUsedInArgOrEnv
  • InvalidDefaultArgInFrom
  • RedundantTargetPlatform
  • CopyIgnoredFile (experimental)
  • FromPlatformFlagConstDisallowed
• Many performance improvements for working with big Dockerfiles.moby/buildkit#5067,moby/buildkit#5029
• Fix possible panic when building Dockerfile without defined stages.moby/buildkit#5150
• Fix incorrect JSON parsing that could cause some incorrect JSON values to pass without producing an error.moby/buildkit#5107
• Fix a regression where COPY --link with a destination path of . could fail.moby/buildkit#5080
• Fix validation of ADD --checksum when used with a Git URL.moby/buildkit#5085 2024-06-18

The full release note for this release is availableon GitHub.

Bug fixes and enhancements

• Fix handling of empty strings on variable expansion.moby/buildkit#5052
• Improve formatting of build warnings.moby/buildkit#5037,moby/buildkit#5045,moby/buildkit#5046
• Fix possible invalid output for UndeclaredVariable warning for multi-stage builds.moby/buildkit#5048 2024-06-11

The full release note for this release is availableon GitHub.

• Many new validation rules have been added to verify that your Dockerfile is using best practices. These rules are validated during build and new check frontend method can be used to only trigger validation without completing the whole build.
• New directive #check and build argument BUILDKIT_DOCKERFILE_CHECK lets you control the behavior or build checks.moby/buildkit#4962
• Using a single-platform base image that does not match your expected platform is now validated.moby/buildkit#4924
• Errors from the expansion of ARG definitions in global scope are now handled properly.moby/buildkit#4856
• Expansion of the default value of ARG now only happens if it is not overwritten by the user. Previously, expansion was completed and value was later ignored, which could result in an unexpected expansion error.moby/buildkit#4856
• Performance of parsing huge Dockerfiles with many stages has been improved.moby/buildkit#4970
• Fix some Windows path handling consistency errors.moby/buildkit#4825 2024-03-06

Stable

• Variable expansion now allows string substitutions and trimming.moby/buildkit#4427,moby/buildkit#4287
• Named contexts with local sources now correctly transfer only the files used in the Dockerfile instead of the full source directory.moby/buildkit#4161
• Dockerfile now better validates the order of stages and returns nice errors with stack traces if stages are in incorrect order.moby/buildkit#4568,moby/buildkit#4567
• History commit messages now contain flags used with COPY and ADD.moby/buildkit#4597
• Progress messages for ADD commands from Git and HTTP sources have been improved.moby/buildkit#4408

Labs

• New --parents flag has been added to COPY for copying files while keeping the parent directory structure.moby/buildkit#4598,moby/buildkit#3001,moby/buildkit#4720,moby/buildkit#4728,docs
• New --exclude flag can be used in COPY and ADD commands to apply filter to copied files.moby/buildkit#4561,docs 2023-06-13

New

• Add --start-interval flag to theHEALTHCHECK instruction.

The following features have graduated from the labs channel to stable:

• The ADD instruction can nowimport files directly from Git URLs
• The ADD instruction now supports--checksum flagto validate the contents of the remote URL contents

Bug fixes and enhancements

• Variable substitution now supports additional POSIX compatible variants without :.moby/buildkit#3611
• Exported Windows images now contain OSVersion and OSFeatures values from base image.moby/buildkit#3619
• Changed the permissions for Heredocs to 0644.moby/buildkit#3992 2023-02-14

Bug fixes and enhancements

• Fix building from Git reference that is missing branch name but contains a subdir
• 386 platform image is now included in the release 2023-01-18

Bug fixes and enhancements

• Fix possible panic when warning conditions appear in multi-platform builds 2023-01-10

Important

The labs channel gives you access to experimental Dockerfile features not yet available in the stable channel.

New

• ADD command now supports--checksum flagto validate the contents of the remote URL contents 2023-01-10

New

• ADD command can nowimport files directly from Git URLs

Bug fixes and enhancements

• Named contexts now support oci-layout:// protocol for including images from local OCI layout structure
• Dockerfile now supports secondary requests for listing all build targets or printing outline of accepted parameters for a specific build target
• Dockerfile #syntax directive that redirects to an external frontend image now allows the directive to be also set with // comments or JSON. The file may also contain a shebang header
• Named context can now be initialized with an empty scratch image
• Named contexts can now be initialized with an SSH Git URL
• Fix handling of ONBUILD when importing Schema1 images 2022-08-23

Bug fixes and enhancements

• Fix creation timestamp not getting reset when building image fromdocker-image:// named context
• Fix passing --platform flag of FROM command when loadingdocker-image:// named context 2022-05-06

Bug fixes and enhancements

• Fix loading certain environment variables from an image passed with built context 2022-04-08

Bug fixes and enhancements

• Fix named context resolution for cross-compilation cases from input when input is built for a different platform 2022-03-09

New

• COPY --link and ADD --linkallow copying files with increased cache efficiency and rebase images without requiring them to be rebuilt. --link copies files to a separate layer and then uses new LLB MergeOp implementation to chain independent layers together
• Heredocs support have been promoted from labs channel to stable. This feature allows writing multiline inline scripts and files
• Additionalnamed build contextscan be passed to build to add or overwrite a stage or an image inside the build. A source for the context can be a local source, image, Git, or HTTP URL
• BUILDKIT_SANDBOX_HOSTNAME build-argcan be used to set the default hostname for the RUN steps

Bug fixes and enhancements

• When using a cross-compilation stage, the target platform for a step is now seen on progress output
• Fix some cases where Heredocs incorrectly removed quotes from content 2021-10-04

Bug fixes and enhancements

• Fix parsing "required" mount key without a value 2021-07-16

Important

The labs channel gives you access to experimental Dockerfile features not yet available in the stable channel.

New

• RUN and COPY commands now supportHere-document syntaxallowing writing multiline inline scripts and files 2021-07-16

New

• RUN command allows--network flagfor requesting a specific type of network conditions. --network=hostrequires allowing network.host entitlement. This feature was previously only available on labs channel

Bug fixes and enhancements

• ADD command with a remote URL input now correctly handles the --chmod flag
• Values forRUN --mount flagnow support variable expansion, except for the from field
• AllowBUILDKIT_MULTI_PLATFORM build argto force always creating multi-platform image, even if only contains single platform 2020-12-12

Important

The labs channel gives you access to experimental Dockerfile features not yet available in the stable channel.

Bug fixes and enhancements

• RUN command allows--network flagfor requesting a specific type of network conditions. --network=hostrequires allowing network.host entitlement 2020-12-12

Bug fixes and enhancements

• Revert "Ensure ENTRYPOINT command has at least one argument"
• Optimize processing COPY calls on multi-platform cross-compilation builds 2020-12-03

Important

The labs channel gives you access to experimental Dockerfile features not yet available in the stable channel.

Bug fixes and enhancements

• Experimental channel has been renamed to labs 2020-12-03

New

• RUN --mount syntax for creating secret, ssh, bind, and cache mounts have been moved to mainline channel
• ARG command now supports defining multiple build args on the same line similarly to ENV

Bug fixes and enhancements

• Metadata load errors are now handled as fatal to avoid incorrect build results
• Allow lowercase Dockerfile name
• --chown flag in ADD now allows parameter expansion
• ENTRYPOINT requires at least one argument to avoid creating broken images 2020-04-18

Bug fixes and enhancements

• Forward FrontendInputs to the gateway 2019-07-31

Important

The labs channel gives you access to experimental Dockerfile features not yet available in the stable channel.

Bug fixes and enhancements

• Allow setting security mode for a process with RUN --security=sandbox|insecure
• Allow setting uid/gid forcache mounts
• Avoid requesting internally linked paths to be pulled to build context
• Ensure missing cache IDs default to target paths
• Allow setting namespace for cache mounts withBUILDKIT_CACHE_MOUNT_NS build arg 2019-07-31

Bug fixes and enhancements

• Fix workdir creation with correct user and don't reset custom ownership
• Fix handling empty build args also used as ENV
• Detect circular dependencies 2019-04-27

New

• ADD/COPY commands now support implementation based on llb.FileOp and do not require helper image if builtin file operations support is available
• --chown flag for COPY command now supports variable expansion

Bug fixes and enhancements

• To find the files ignored from the build context Dockerfile frontend will first look for a file <path/to/Dockerfile>.dockerignore and if it is not found .dockerignore file will be looked up from the root of the build context. This allows projects with multiple Dockerfiles to use different.dockerignore definitions