Headless mode runs a real browser under Selenium control without opening a visible browser window. Your script still loads pages, executes JavaScript and interacts with the browser; only the graphical window is hidden. In current Selenium Chrome examples, enable it by adding --headless=new to a ChromeOptions object. The old setHeadless convenience method was deprecated in Selenium 4.8 and removed in 4.10, so new code should configure a browser argument instead.
What headless mode actually means
Selenium is still driving Chrome, Firefox or another supported browser. “Headless” describes the browser’s display mode, not a different Selenium product or a lightweight HTTP client. The browser process starts without its normal desktop window, which is useful on CI workers, servers and containers where no graphical desktop is available.
A headless session can navigate to a URL, find elements, submit forms, run JavaScript and produce page output just like a headed session. The important distinction is visibility: a headed run displays a window that a person can watch, while a headless run does not.
| Aspect | Headless run | Headed run |
|---|---|---|
| Browser window | Not displayed | Displayed on the desktop or virtual display |
| How Selenium enables it | Browser-specific option or command-line argument | No headless argument |
| Best fit | CI jobs, scheduled scripts and machines without a desktop | Interactive debugging and watching a test execute |
| Rendering or speed claims | Must be checked in your browser version and environment; the available Selenium material does not establish that headless is always faster, more stable or pixel-identical | |
Enable headless Chrome with current Selenium
For Chrome, create a ChromeOptions instance and add --headless=new. This is the current Selenium-documented pattern.
#1 Best Overall
- Install a current Selenium 4 binding for your language.
- Ensure Chrome is installed. Selenium’s Chrome guidance says Selenium 4 supports Chrome 75 and newer and that Chrome and ChromeDriver major versions should match; verify the versions on the machine you actually run.
- Create the options object and add the headless argument.
- Pass the options object when constructing the driver.
- Always call
quit()in a cleanup block so the browser process does not remain after a failure.
Runnable Python example
from selenium import webdriver
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()
The script prints the page title without opening a Chrome window. The URL is only an example; replace it with the page your test or automation needs.
Node.js example
const { Builder } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');
(async function () {
const options = new chrome.Options();
options.addArguments('--headless=new');
const driver = await new Builder()
.forBrowser('chrome')
.setChromeOptions(options)
.build();
try {
await driver.get('https://example.com');
console.log(await driver.getTitle());
} finally {
await driver.quit();
}
}());
Java example
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
public class HeadlessChrome {
public static void main(String[] args) {
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
WebDriver driver = new ChromeDriver(options);
try {
driver.get("https://example.com");
System.out.println(driver.getTitle());
} finally {
driver.quit();
}
}
}
Why older tutorials use setHeadless
Older Selenium examples often call a convenience method such as options.setHeadless(true). Selenium deprecated that method in version 4.8 and removed it in 4.10. Replace it with the browser argument in the options object:
options.add_argument("--headless=new")Chromium’s flags also changed over time. Selenium’s January 2023 migration explanation describes the traditional mode, --headless=chrome for Chrome versions 96–108, and --headless=new from version 109. Those are historical transition details. For a current installation, use the flag documented for the browser version you deploy rather than copying a legacy snippet.
A Selenium 4.18 release note (February 19, 2024) additionally noted a Chrome headless browser-name change and advised switching to --headless=new. Treat that as compatibility history, not a promise that every future browser release will retain the same behavior.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsHeadless is browser-specific
Do not assume Chrome’s argument works unchanged for Firefox, Edge or every Chromium-based browser. Selenium documents Firefox-specific support and options separately. Its Firefox guidance requires Firefox 78 or newer for Selenium 4 and recommends the latest geckodriver; check the current Firefox binding documentation before choosing a flag.
Rank #2
The general API idea is consistent: instantiate the selected browser’s options class, set the browser-specific headless capability or argument, then pass that object to the driver. For remote execution, Selenium’s browser-options documentation says the options instance determines which browser the remote session uses.
Driver, browser and Selenium setup
Version compatibility
When a session fails before your first page loads, check the local browser and driver versions first. Selenium’s Chrome documentation calls out matching Chrome and ChromeDriver major versions. Firefox sessions have their own Firefox/geckodriver compatibility requirements. A working script on one workstation can fail on a CI image with a different browser build.
Selenium Manager
Selenium Manager is Selenium’s official driver manager and has shipped with Selenium releases since 4.6. It can manage drivers and, under documented conditions, browsers for you. It still cannot guarantee downloads in an offline machine, a network that blocks the required host, or a locked-down build environment. In those cases, install compatible browser and driver binaries through your image or operating-system process and ensure they are discoverable by the binding.
Remote sessions
For Selenium Grid or another remote server, create the options object locally and send it with the session request. The remote machine—not your laptop—must have a compatible browser and driver, and it is the remote machine’s display configuration that determines whether a window can be shown.
What headless mode does not guarantee
Headless removes the visible window; it is not a guarantee of a particular performance profile. The reviewed Selenium material does not provide a benchmark proving that headless runs are always faster or more reliable. It also does not establish pixel-for-pixel identity between headless and headed rendering across operating systems, browser versions, fonts and GPU configurations.
For visual regression work, compare screenshots produced in the same browser build, viewport and environment. For functional tests, keep assertions focused on the behavior you need and retain a headed configuration for diagnosing failures.
Practical patterns for CI and debugging
Use one configuration switch
Keep the rest of your test setup identical and make headless a deliberate option. A common pattern is to add --headless=new when a CI setting is enabled, while leaving it out for a local debugging run. This lets you reproduce a failure with a visible window without maintaining two unrelated test suites.
Capture useful failure evidence
When a headless test fails, record the URL, exception, browser version and driver version. Saving a screenshot or page source at the failure point can reveal that the page was still loading, redirected, or displayed a consent dialog. Do not infer from the absence of a visible window that the browser did not start.
Wait for the application, not the window
Because nobody can watch a headless run, synchronization matters. Wait for the application state your test needs (for example, an element becoming available) rather than assuming navigation has finished immediately. Keep waits and timeouts explicit so a slow CI machine fails with a useful diagnostic instead of an unexplained later error.
Troubleshooting common errors
“Unknown option” or setHeadless attribute errors
Cause: code uses the removed convenience method or passes a flag to the wrong options class. Fix: use the selected browser’s options object and its documented argument; for current Chrome, add --headless=new.
SessionNotCreatedException or browser-version mismatch
Cause: the browser and driver major versions do not match, or the remote machine has a different browser than expected. Fix: print or inspect both versions, update the pair together, and verify the Selenium binding version. Selenium Manager may help when the environment can access required downloads; it cannot solve every offline or restricted network.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Chrome starts locally but not in CI
Cause: the CI image lacks Chrome, a compatible driver, required libraries, or network access for Selenium Manager. Fix: build those dependencies into the image, confirm executable permissions and paths, and test the exact image interactively. The headless flag removes the need for a visible desktop, not the need for a browser installation.
Firefox ignores the Chrome argument
Cause: browser-specific configuration was mixed. Fix: use Firefox’s options and current geckodriver guidance instead of copying Chrome’s argument.
Headless output differs from a headed screenshot
Cause: browser version, viewport, fonts, device settings or other environment differences. Fix: hold those variables constant, compare like-for-like runs, and avoid treating headless/headed equivalence as automatic.
The script hangs or leaves processes behind
Cause: a failed setup path skipped cleanup, or navigation waits indefinitely. Fix: put driver shutdown in a finally block, set appropriate page and script timeouts, and capture the exception and current URL before exiting.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Or skip the browser setup
If your goal is a clean website image or PDF rather than browser interaction, ScreenshotNeo provides a single screenshot API request. Its cleanup steps accept cookie or consent banners like a visitor and remove more than 60 known consent platforms, newsletter popups and chat widgets before capture; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the page verdict and billing status in headers.
See the ScreenshotNeo API documentation for all options. A minimal cURL request is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to get started.
Frequently Asked Questions
Does headless mode mean Selenium is not using a browser?
No. Selenium still launches and controls the selected browser; headless only suppresses its visible window.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, 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 minuteCan I turn headless mode on with a Selenium capability instead of an argument?
Use the options class and browser-specific configuration documented for your binding and browser version. Current Chrome guidance uses the --headless=new argument.
Should I develop tests headless from the beginning?
Use headless where the execution environment requires it, but keep a headed configuration available so you can observe and diagnose failures locally.
Is headless mode available for Firefox?
Selenium documents Firefox support, but Firefox uses browser-specific options. Do not copy Chrome’s argument without checking the current Firefox and geckodriver documentation.
The Bottom Line
Headless mode is Selenium running a real browser without displaying its window. Configure it through the browser’s options—--headless=new for current Chrome examples—keep browser and driver versions compatible, and validate rendering and reliability in the environment where your tests run.
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.
