Chrome Headless is Changing

Page last updated: January 2024

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

By upgrading to HyJavaImages library v1.9.0 or newer the library will operate correctly until at least the Headless Stage 4 changes are implemented.

By upgrading to HyJavaImages library v1.9.0 or newer and downloading and installing the standalone chrome-headless-shell binary, the library will operate correctly. Stage 3 and 4 changes will have no impact. You will continue to use the “old” Chrome Headless.

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 or newer the default is to specifically use the “old” Chrome headless.
The library automatically adds the argument “–headless=old”.

Testing of Headless “new” showed there were issues creating images of the specified size. The Chrome dev team would not fix.

From HyJavaImages library v1.8.0 a change was implemented so that Headless “new” will now create images of the correct size.

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

Not implemented (no date announced)

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.6.0 or newer. The library default is to use the “old” Chrome headless.

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 or newer the default is to use the “old” Chrome headless. The library will operate correctly.

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.

HyJavaImages library

Your Options:

1. Upgrade to HyJavaImages library v1.9.0 or newer. The library will operate correctly using “new” headless mode with the following change:

Chrome chrome = Chrome.getInstance();
chrome.setChromeArguments(new ChromeArguments().setChromeHeadlessType(ChromeHeadlessType.HEADLESS_NEW));
chrome.start();

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.

New Chrome Headless Testing

Users that wish to test the “new” Chrome headless can do so with HyJavaImages library v1.8.0 or newer and the following Chrome arguments.

Chrome chrome = Chrome.getInstance();
chrome.setChromeArguments(new ChromeArguments().setChromeHeadlessType(ChromeHeadlessType.HEADLESS_NEW));
chrome.start();

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

You will need to use the ChromeArguments class setChromeHeadlessType(ChromeHeadlessType.HEADLESS_NEW) method when starting Chrome, see below.

Chrome chrome = Chrome.getInstance();
chrome.setChromeArguments(new ChromeArguments().setChromeHeadlessType(ChromeHeadlessType.HEADLESS_NEW));
chrome.start();