Skip to content
Choose a tag to compare
  • Fixed: Batect could fail with error messages like java.lang.NoSuchMethodError: 'java.util.List' when running on Java 15 or earlier.
Choose a tag to compare
  • New: checksums for the wrapper scripts will now be published for each release and attached to the GitHub release (see 'assets' below)

    These checksums can be used to easily verify the integrity of the wrapper scripts used in your project.

    For example, these checksums are used by the new batect-wrapper-validation-action action, which validates the integrity of the wrapper scripts as part of a GitHub Actions workflow.

  • Fixed: downloading update information and updated files and uploading telemetry data (if opted-in) would fail if your system connects to the internet via an encryption-terminating proxy that was not trusted by your Java installation.

    These features will now work correctly on macOS and Windows provided your operating system certificate settings are configured to trust the proxy's certificate, which matches the behaviour of browsers and other tools.

    ⚠️ If you use macOS, it's recommended you upgrade to one of the following Java versions to fix a security vulnerability related to this functionality:

    • JDK 8: 8u332 or later
    • JDK 11: 11.0.15 or later
    • JDK 17: 17.0.3 or later
    • JDK 18: 18.0.1 or later
    • All versions of JDK 19 or later
Choose a tag to compare
  • Changed: Batect will now use BuildKit for image builds by default if the Docker daemon reports that it supports BuildKit (#1156 - thanks to @sschuberth for the issue report)

    BuildKit improves the performance of image builds, as well as adding many new features. Not all of BuildKit's features are currently supported by Batect.

    Batect's BuildKit support has been in use for many months now and there are no known issues. If you encounter any issues as a result of this change, disable BuildKit by setting the DOCKER_BUILDKIT environment variable to 0 and report an issue.

Choose a tag to compare
  • Fixed: Batect would hang if --no-cleanup or --no-cleanup-after-success was used and a container had a health check defined (#1135 - thanks to @hpcsc for the bug report)

  • Fixed: containers would sometimes be stopped and sometimes be left running if --no-cleanup or --no-cleanup-after-failure was used, depending on how the containers were configured. Now containers will always be stopped.

  • Fixed: Batect could crash, show an error message or silently use incorrect console dimensions when running on Apple Silicon machines. This could also lead to difficult to read output when text exceeded the width of the console and was not correctly trimmed.

Thank you also to @sschuberth for yet another round of improvements to the build setup for Batect.

Choose a tag to compare


  • Fixed: Batect would fail to start on devices with Apple Silicon chips (#963 - thanks to @smozely and @jgv115 for reporting and helping to diagnose this issue)
Choose a tag to compare


  • New: -h can now be used as an alias for --help on the command line (#1082 - thanks to @binkley for the PR)
  • Fixed: Batect did not correctly detect mintty as an interactive environment (#1014 / #1082 - thanks to @sschuberth for the bug report and @svishal9 for the PR)
Choose a tag to compare


  • Fixed: the Unix user and group for run as current user mode was not correctly applied to the home directory or any cache directories if they ended with a trailing slash in the configuration file, preventing processes within the container from using these directories
Choose a tag to compare


  • New: it is now possible to clean only a single cache rather than all of the caches in a project (#1010 and #1055 - thanks to @sschuberth for the suggestion and @svishal9 for the PR)

    --clean removes all caches for the project, whereas the new --clean-cache option option allows specifying one or more caches to clean.

    For example, run ./batect --clean-cache=node-modules to clean the cache named node-modules.

  • Fixed: Batect would still prompt for telemetry consent even if forbid_telemetry was set to true for the project (#1028 - thanks to @sschuberth for reporting this issue)

Choose a tag to compare


  • New: it is now possible to disable telemetry for a project, overriding any other consent to telemetry. (#1028 - thanks to @sschuberth for suggesting this)

    Set forbid_telemetry to true in your project to disable telemetry in your project.

  • New: Batect now respects the JAVA_HOME environment variable (#1016 - thanks to @sschuberth for suggesting this)

  • Fixed: Batect could fail to build an image if the Unix user on the host machine had a UID larger than 2097151 (#1027 and #1029 - thanks to @kbalston for reporting and fixing this issue)

  • Fixed: the schema used for code completion of configuration files in IDEs did not comply with the JSON schema version it claimed to comply with (#1039 - thanks to @ineffyble for reporting and fixing this issue)

  • Improved: if the background upload of telemetry data fails repeatedly, give up early rather than trying to upload all queued data

Thank you also to @sschuberth for a number of pull requests improving the build setup and cleaning up some of the codebase (#1007, #1015, #1017, #1024, #1033, #1054)

Choose a tag to compare


I've recently published two RFCs covering significant enhancements to Batect:

  • #990: new expression syntax
  • #991: bundle scoping

The RFC process is intended to allow anyone with an interest in Batect to get involved and help shape it to suit their needs, so please don't be shy! Any comments, suggestions, questions or constructive criticism are more than welcome.


  • Improved: caches no longer need to be initialised with a separate container and will be no longer have a .cache-init file created within them.

    This improves performance (as there's no longer a need to start and run another container to prepare caches before they're used), and fixes issues where some applications insist on a completely empty directory, such as Postgres (#1000 - thanks to @ineffyble for the feedback).

    The --linux-cache-init-image option has been removed as it is no longer used.

    Note that this change in behaviour does mean that caches using volumes (ie. not using directories with --cache-type=directory) will now inherit the contents of the target directory from the image when they are created for the first time. Previously, they would always contain only the dummy .cache-init file. For example, if a cache is mounted at /cache, and the image for the container contains files in /cache, when the cache volume is created for the first time, the contents of /cache from the image will be copied into the volume.

Thank you

Thank you also to @sschuberth for submitting a number of PRs to improve some of the behind-the-scenes developer tooling.