Headless Chrome runs Selenium tests without displaying a browser window; it is not a different browser engine. Modern Chrome shares the same implementation between headless and headed modes, but tests can still behave differently when their viewport, fonts, permissions, browser versions, or runtime environment differ. Set those inputs deliberately, save evidence when a test fails, and measure speed on your own CI runner rather than assuming headless is always faster.
What headless mode changes—and what it does not
Chrome describes headless mode as running the browser unattended, without visible UI. Since Chrome 112, its unified implementation creates platform windows but does not display them; Chrome says other browser functionality is available without limitations in this mode (Chrome for Developers). Selenium enables the mode through Chrome command-line arguments.
The practical difference is visibility: headed mode gives you a window to watch, while headless mode does not. That changes how you diagnose a failure, not the Selenium locator API. A test that passes in one mode and fails in the other may instead be seeing different dimensions, fonts, permissions, resource constraints, or browser and driver versions.
Current Chrome versus the legacy headless implementation
For Chrome 112 onward, the default unified headless mode shares Chrome’s code path with headed mode. Chrome 132.0.6793.0 introduced the old, separate implementation as the standalone chrome-headless-shell binary. Unless a legacy workload specifically requires that shell, use current Chrome’s unified headless mode.
#1 Best Overall
Configure Selenium headless mode and the viewport
Pass a headless argument through ChromeOptions and set the browser window dimensions explicitly for layout-sensitive tests. Selenium deprecated its convenience headless method in version 4.8.0 and removed it in 4.10.0; use an explicit Chromium argument instead (Selenium 4.8.0 release notes; Selenium 4.10.0 release notes). Chrome documents both --headless and the window-size flag (Chrome Headless documentation).
Java example
With Selenium’s Java binding installed and Chrome available to the runner, this creates a headless session at a fixed window size. Use the same URL and assertions as in your headed test.
import org.openqa.selenium.Dimension;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
public class HeadlessCheck {
public static void main(String[] args) {
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new", "--window-size=1440,1000");
WebDriver driver = new ChromeDriver(options);
try {
driver.get("https://example.com");
System.out.println(driver.getTitle());
driver.manage().window().setSize(new Dimension(1440, 1000));
} finally {
driver.quit();
}
}
}The explicit window-size argument makes the intended initial dimensions clear; the WebDriver call sets the window size as well. Choose dimensions that match the test’s intended layout, not merely a convenient default. Record them with test artifacts so that a responsive breakpoint mismatch is easier to recognize.
Rank #2
Python example
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.add_argument("--headless=new")
options.add_argument("--window-size=1440,1000")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()In Selenium 4, do not rely on a removed options.headless convenience property; supply the browser mode as an argument. If a binding or Chrome release documents a current --headless form for your setup, use its documented form and pin the browser version used by CI.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why a test may pass headed but fail headless
Viewport and responsive layout
A different viewport can trigger another CSS breakpoint, collapse navigation, move an element, or change which control is visible. That is a rendering-input difference, not evidence that Selenium’s locator behavior changed. Set dimensions explicitly in both modes when comparing results, and check the actual element visibility and position before changing selectors.
Fonts, graphics, permissions, and runner resources
The unified implementation is designed to share Chrome functionality, but the machine still matters. A CI container may have different fonts, GPU availability, permissions, resource limits, shared memory, or network conditions from a developer’s desktop. If the failure only occurs in one environment, compare those inputs before treating headless mode itself as the cause.
Browser, driver, and Selenium versions
Selenium says Chrome and ChromeDriver major versions should match (Selenium Chrome documentation). Chrome for Testing distributes paired browser and driver binaries across release channels (Chrome for Testing availability). Keep the browser, driver, Selenium binding, and CI container image under deliberate version control rather than letting an unpinned update silently change the test environment.
Display dependencies
Headed Chrome needs a desktop display environment. Headless Chrome does not use a displayed window, and Chrome says a display server such as Xvfb is no longer needed for it (Chrome Headless documentation). This makes headless convenient on unattended runners, but does not remove the need to provide the browser’s other runtime dependencies.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteCapture evidence when a headless test fails
Without a visible window, use artifacts to understand what Chrome rendered at the failure point. Selenium can save a screenshot, and Chrome’s headless tools can capture screenshots or serialize the page DOM. Chrome’s --dump-dom parses the page, runs scripts that alter the DOM, then serializes the resulting DOM; it is not simply a copy of the original HTML source (Chrome Headless documentation).
Rank #4
- Used Book in Good Condition
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.add_argument("--headless=new")
options.add_argument("--window-size=1440,1000")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
# Run the test's action or assertion here.
driver.save_screenshot("failure-point.png")
with open("failure-point.html", "w", encoding="utf-8") as output:
output.write(driver.page_source)
finally:
driver.quit()Save the screenshot and DOM at the point of failure, along with browser logs and the test’s viewport and version information. Compare them with a headed run using the same URL, data, dimensions, and browser version. A screenshot makes layout differences visible; the DOM helps distinguish a missing element from one that rendered but was positioned or styled unexpectedly.
Remote DevTools for CI-only failures
You can start Chrome with remote debugging and inspect its target from a normal Chrome DevTools window, even when the failing browser has no desktop session (Chrome Headless documentation). Treat the debugging endpoint as a sensitive diagnostic interface: expose it only in a controlled environment and close it when the investigation is complete.
Does headless Chrome make Selenium faster?
There is no universal headless-versus-headed speed multiplier established by the official sources cited here. Headless avoids displaying a UI and can simplify unattended execution, but a particular suite’s wall time and resource use depend on its pages and runner. Compare modes on the same machine with the same browser and driver versions, viewport, test data, and network conditions. Track wall time, failure rate, and resource use across repeated runs; do not infer a speed improvement from one test or a different CI machine.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Best Value
Practical CI strategy
- Pin the environment. Record Chrome, ChromeDriver, Selenium binding, and container image versions. Keep Chrome and ChromeDriver on matching major versions.
- Set the display mode and dimensions. Use ChromeOptions with an explicit headless argument and a fixed window size for layout-sensitive tests.
- Keep failure artifacts. Save screenshots, browser logs, and DOM or page-source output when a test fails. Preserve enough information to reproduce the run.
- Compare like with like. When reproducing locally, use the CI browser binary, flags, viewport, permissions, fonts, and relevant network conditions.
- Retain headed runs where useful. Headless is convenient for unattended execution; a headed diagnostic or parity job can help when a visual issue is hard to interpret. Neither mode substitutes for checking the actual runner inputs.
Troubleshooting common failures
| Symptom | Likely cause to check | What to do |
|---|---|---|
| Chrome starts headed instead of headless | The headless argument was omitted, misspelled, or set through a convenience method removed from the Selenium version in use. | Add the documented Chrome argument through ChromeOptions and verify the effective options in the CI run. |
| Layout or element visibility differs | The viewport dimensions differ, so responsive CSS selects another layout. | Set a fixed window size and compare screenshots at that same size in both modes. |
| Session fails to start after an update | Chrome and ChromeDriver major versions may not match, or the container image changed. | Pin the versions, align browser and driver major versions, then reproduce using the same binaries. |
| A visual result differs only in CI | Fonts, GPU availability, permissions, shared memory, resource limits, or network conditions may differ from the local machine. | Compare those environment inputs and inspect a failure-time screenshot and browser logs before changing the test. |
| Cannot see what the page rendered | Headless mode has no visible browser window for interactive observation. | Save a screenshot and DOM at the failure point, or use remote debugging to inspect the target from Chrome DevTools. |
Or skip the browser setup
For a standalone screenshot of a page rather than a Selenium interaction or assertion, ScreenshotNeo is a website screenshot API and MCP server. It does not replace Selenium for exercising an application, but it can provide a screenshot without configuring a local browser capture script. One GET request returns an image or PDF; the example below saves the response as WebP. See the ScreenshotNeo documentation for API options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server provides screenshot and page-information tools for AI agents. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently Asked Questions
Can I use headed Chrome for one CI job and headless Chrome for the rest?
Yes. Keep the browser and driver versions, viewport, test data, and other relevant environment inputs aligned so the comparison is meaningful.
Free tools Windows power users keep installed
One-click scans. No signup required.
Does `–headless=new` mean Chrome uses a separate browser engine?
No. In current unified Headless, Chrome uses the shared implementation and does not display its platform windows.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
