Chrome Headless is Changing

Page last updated: October 2024

Overview

The Chrome dev team are updating Chrome Headless. Stage 1, 2 and 3 changes have been implemented. Stage 4 changes are yet to be implemented.
We will update this page as the Chrome dev team progress.

By upgrading to HyJavaImages library v1.12.0 or newer the library will operate correctly as these changes progress.

Chrome Versions 111 and Older

For Chrome versions 111 and older, there is only one version of Chrome headless available.
The Chrome argument “–headless” will start Chrome in headless mode.

For HyJavaImages library v1.5.6 and older, the library automatically adds the argument “–headless”.

Headless Stage 1 Changes

Implemented April 2023

For Chrome versions 112 and newer, there are now “old” and “new” Chrome headless versions available.

The Chrome argument “–headless” will start Chrome in the “old” headless mode until Stage 3 changes are implemented.
The Chrome argument “–headless=old” will start Chrome in the “old” headless mode.
The Chrome argument “–headless=new” will start Chrome in the “new” headless mode.

HyJavaImages library

For HyJavaImages library v1.5.6 and older, the library will operate correctly using the “old” Chrome headless until Stage 3 changes are implemented.
The library automatically adds the argument “–headless”.

For HyJavaImages library v1.6.0 – v1.11.0 the default is to specifically use the “old” Chrome headless.
The library automatically adds the argument “–headless=old”.

Headless Stage 2 Changes

Implemented December 2023

For Chrome versions 120 and newer, the “old” Headless implementation is now available as a standalone chrome-headless-shell binary.

HyJavaImages library

No changes are required.

You now have the option to download and install the standalone chrome-headless-shell binary. Then use the Chrome class setChromeBinaryPath() method to point at that binary. Doing this will mean Stage 3 and 4 changes will have no impact. You will be using the “old” Chrome Headless.

From HyJavaImages library v1.9.0 and newer, the library will look for the standalone chrome-headless-shell binary first. If its installed in the standard locations, you will not need to use the setChromeBinaryPath() method to find it.

Headless Stage 3 Changes

Implemented August 2024

For Chrome versions 128 and newer, the Chrome argument “–headless” will now start Chrome in the “new” headless mode.

HyJavaImages library

Users on HyJavaImages library v1.5.6 and older will see errors.

Your Options:

1. Upgrade to HyJavaImages library v1.12.0 or newer. The library default is to use the “new” Chrome headless. The library will operate correctly.

2. Remain on HyJavaImages library v1.5.6 or older, with the following Chrome arguments.

Chrome chrome = Chrome.getInstance();
chrome.setChromeArguments(new ChromeArguments().removeArgument("--headless").addArgument("--headless=old"));
chrome.start();

3. Remain on a version of Chrome that by default uses the “old” Chrome headless.

4. Download and install the standalone chrome-headless-shell binary. Then use the Chrome class setChromeBinaryPath() method to point at that binary. Doing this will mean Stage 3 and 4 changes will have no impact. You will be using the “old” Chrome Headless.

Users on HyJavaImages library v1.6.0 – v1.11.0 the default is to use the “old” Chrome headless. The library will operate correctly.

In preparation for the removal of “old” headless, for HyJavaImages library v1.12.0 and newer the default is to use the “new” Chrome headless. The default can be changed by using the ChromeArguments class setChromeHeadlessType() method.

Headless Stage 4 Changes

Not implemented (no date announced)

The Chrome dev team will remove the headless “old” binary from the standard Chrome install.
All –headless, –headless=old, –headless=new arguments will now start Chrome in the “new” headless mode.

NOTE: The following message is now appearing when you start Chrome with “–headless=old”:
“Old Headless mode will be removed from the Chrome binary soon.”

HyJavaImages library

Your Options:

1. Upgrade to HyJavaImages library v1.12.0 or newer. The library will operate correctly using the “new” headless mode.

2. Remain on a version of Chrome that by default uses the “old” Chrome headless.

3. Download and install the standalone chrome-headless-shell binary. Then use the Chrome class setChromeBinaryPath() method to point at that binary. Doing this will mean Stage 4 changes will have no impact. You will be using the “old” Chrome Headless.

Old vs New Chrome Headless

The old Headless mode is a lightweight wrapper around Chromium’s //content module, and it therefore has substantially fewer dependencies. Specifically, it does not require X11/Wayland, D-Bus, and is in some ways more performant than the fully-fledged Chrome browser. This makes it suitable for use cases such as automated screenshotting or web scraping.

New Headless on the other hand is the real Chrome browser, and is thus more authentic, reliable, and offers more features. This makes it more suitable for high-accuracy end-to-end web app testing or browser extension testing.

In other words, there’s a trade-off between performance and authenticity. Which Headless mode is most fitting for you? It depends on your use case.

HyJavaImages library

The HyJavaImages library will offer the choice to use “old” or “new” headless.

Old Headless

This is our recommended option.

Download and install the standalone chrome-headless-shell binary. Then use the Chrome class setChromeBinaryPath() method to point at that binary.

You will get a known version of Chrome Headless that the HyJavaImages library has been fully tested against.
It will not be updated until a new matching version of the HyJavaImages library is released.

New Headless

Upgrade to HyJavaImages library v1.12.0 or newer. The library will operate correctly using the “new” headless mode.