Page last updated: November 2024
Overview
The Chrome dev team are updating Chrome Headless. Stage 1, 2 and 3 changes have been implemented.
Stage 4 changes are planned for Chrome 132 (January 2025 – TBC). 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. We recommend you also upgrade to HyJavaImages library v1.12.0 or newer.
For HyJavaImages library v1.8.0 and older, you will need to use the Chrome class setChromeBinaryPath() method to point at that binary.
For 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.
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
Implementation planned for January 2025 – TBC (Chrome 132)
The Chrome dev team will remove the headless “old” binary from the standard Chrome install.
Starting Chrome with the –headless=old argument will fail. There will be a RuntimeException: “Chrome headless server has not started.”
The message “Old Headless mode has been removed from the Chrome binary…” may also be displayed.
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. We recommend you also upgrade to HyJavaImages library v1.12.0 or newer.
For HyJavaImages library v1.8.0 and older, you will need to use the Chrome class setChromeBinaryPath() method to point at that binary.
For 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.
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. We recommend you also upgrade to HyJavaImages library v1.12.0 or newer.
You will get a known version of Chrome Headless that the HyJavaImages library has been fully tested against.
For HyJavaImages library v1.8.0 and older, you will need to use the Chrome class setChromeBinaryPath() method to point at that binary.
For 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.
New Headless
Upgrade to HyJavaImages library v1.12.0 or newer. The library will operate correctly using the “new” headless mode.